Astro GitHub JavaScript Markdown Web開発オープンソース

Astroでカスタマイズ可能な目次を生成する「astro-custom-toc」

2024年3月3日20:402024年3月4日01:33

Astroでカスタマイズ可能な目次を生成するAstro integration「astro-custom-toc」を作りました！

この記事では、astro-custom-tocの使い方や他のプラグインとの違い、カスタマイズ方法などについて説明します。

I just released my first @astrodotbuild integration! 🥳 It generates a customizable table of contents for your markdown pages.

初めてのAstro integrationを公開しました！🥳 Markdownのページにカスタマイズ可能な目次を生成します。

astro-custom-toc - npmhttps://t.co/RFDRF1qDhe
— ろぼいん (@keita_roboin) March 3, 2024

これは何？

astro-custom-tocは、Astroで任意の場所に任意の構造の目次を生成するためのAstro integrationです。MarkdownファイルとMDXファイルに対応しています。

GitHub - Robot-Inventor/astro-custom-toc: Astro Integration to generate a customizable table of contents

Astro Integration to generate a customizable table of contents - Robot-Inventor/astro-custom-toc

github.com

Astro Integration to generate a customizable table of contents - Robot-Inventor/astro-custom-toc

https://www.npmjs.com/package/astro-custom-toc

たとえば、次のようなMarkdownファイルがあったとします。

1
---
2
showToc: true
3
---
4

5
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
6

7
<!-- toc -->
8

9
## hoge
10

11
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
12

13
### fuga
14

15
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

このファイルに対して、次のように目次を生成できます。目次を挿入する箇所や目次の構造は、自由に変更できます。

1
<p>
2
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
3
</p>
4
<aside class="toc">
5
    <h2>Contents</h2>
6
    <nav>
7
        <ul>
8
            <li>
9
                <a href="#hoge">hoge</a>
10
            </li>
11
            <ul>
12
                <li><a href="#fuga">fuga</a></li>
13
            </ul>
14
        </ul>
15
    </nav>
16
</aside>
17
<h2 id="hoge">hoge</h2>
18
<p>
19
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
20
</p>
21
<h3 id="fuga">fuga</h3>
22
<p>
23
    Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
24
</p>

他のプラグインとの違い

既存の主要なプラグインとしては、remark-tocがあります。remark-tocは、remark.jsのプラグインで、基本的な機能をすべて備えています。

しかし、remark-tocにはいくつかの制限があります。デフォルトでは、目次は「Contents」「Table of contents」「ToC」などの見出しの下に生成されます。

これによって目次の位置を調整できますが、目次の構造はカスタマイズできません。また、目次を示す見出しを挿入したくない場合もあります。

私は次のような構造の目次を任意の場所に挿入する方法を探していました。

1
<aside class="toc">
2
    <h2>目次</h2>
3
    <nav>
4
        <ul>
5
            <li>
6
                <a href="#hoge">hoge</a>
7
            </li>
8
            <ul>
9
                <li><a href="#fuga">fuga</a></li>
10
            </ul>
11
        </ul>
12
    </nav>
13
</aside>

これをremark-tocで実現するには、毎回<aside class="toc"></aside>と<h2></h2>を手動で挿入する必要があります。また、目次を<nav></nav>で囲むのは（おそらく）不可能です。

このような問題を解決するために、任意の場所に任意の構造の目次を生成する「astro-custom-toc」を開発しました

インストール

ここからは、astro-custom-tocのインストール方法について説明します。

自動インストール

astro-custom-tocは、astro addコマンドに対応しており、次のコマンドでインストールできます。

astro addを使う場合は、このコマンドだけで最低限の設定が完了します。

npx astro add astro-custom-toc

手動インストール

何らかの理由でastro addコマンドが使えない場合は、手動でインストールできます。

まず、次のコマンドでastro-custom-tocをインストールします。

npm install astro-custom-toc

次に、astro.config.mjsにastro-custom-tocを追加します。

1
import { defineConfig } from "astro/config";
2
import customToc from "astro-custom-toc";
3

4
// https://astro.build/config
5
export default defineConfig({
6
    // ... other config
7
    integrations: [
8
        customToc()
9
    ]
10
});

注意

プロジェクトでMDXインテグレーションを利用している場合は、必ずMDXよりも前に読み込んでください。

1
import { defineConfig } from "astro/config";
2
import customToc from "astro-custom-toc";
3

4
// https://astro.build/config
5
export default defineConfig({
6
    // ... other config
7
    integrations: [
8
        customToc(),
9
        mdx()
10
    ]
11
});

MDXよりもあとに読み込むと、次のようなエラーが発生します。

Unexpected character `!` (U+0021) before name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a comment in MDX, use `{/* text */}`)

使い方

astro-custom-tocのインストールが完了したら、実際に使ってみましょう。astro-custom-tocは、MarkdownファイルとMDXファイルに対応しています。

見出しを生成するには、frontmatterにshowToc: trueを追加し、目次を挿入したい場所にコメントを挿入します。

1
---
2
showToc: true
3
---
4

5
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
6

7
<!-- toc -->
8

9
## hoge
10

11
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

これで、astro-custom-tocが目次を生成し、コメントの位置に挿入します。コメントが見つからない場合は、先頭に目次が挿入されます。

カスタマイズ

astro-custom-tocは、次のようなオプションを提供しています。

`template`

生成された目次のHTMLを受け取り、最終的なHTMLを返す関数です。これを使用して、目次をカスタムテンプレートでラップできます。

デフォルトのテンプレート関数：

1
const defaultTemplate = (html) => {
2
    return `
3
<aside class="toc">
4
    <h2>Contents</h2>
5
    <nav>
6
        ${html}
7
    </nav>
8
</aside>`.trim();
9
};

`maxDepth`

生成される目次の最大の深さです。デフォルトは3で、<h3>までの見出しを目次に含めます。

`ordered`

目次を順序付きリスト（<ol>）にするかどうかです。デフォルトはfalseで、目次に<ul>を使用します。

カスタマイズ例

私のブログでは、次のようなオプションを使用しています。

1
import { defineConfig } from "astro/config";
2
import customToc from "astro-custom-toc";
3

4
const tocTemplate = (html) => {
5
    return `
6
<aside class="toc">
7
    <h2>目次</h2>
8
    <nav>
9
        ${html}
10
    </nav>
11
</aside>`.trim();
12
};
13

14
// https://astro.build/config
15
export default defineConfig({
16
    // ... other config
17
    integrations: [
18
        customToc({
19
            template: tocTemplate
20
        }),
21
        mdx()
22
    ]
23
});