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

#Astro#GitHub#JavaScript#Markdown#Web開発#オープンソース
投稿日: 更新日:

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

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

これは何?

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 - Robot-Inventor/astro-custom-toc: Astro Integration to generate a customizable table of contents favicon github.com
GitHub - Robot-Inventor/astro-custom-toc: Astro Integration to generate a customizable table of contents
astro-custom-toc
Astro Integration to generate a customizable table of contents. Latest version: 2.0.10, last published: 22 days ago. Start using astro-custom-toc in your project by running `npm i astro-custom-toc`. There are no other projects in the npm registry using astro-custom-toc.
astro-custom-toc favicon www.npmjs.com
astro-custom-toc

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

index.md
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.

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

index.html
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」などの見出しの下に生成されます。

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

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

index.html
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を使う場合は、このコマンドだけで最低限の設定が完了します。

Terminal window
npx astro add astro-custom-toc

手動インストール

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

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

Terminal window
npm install astro-custom-toc

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

astro.config.mjs
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
});

使い方

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

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

index.md
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が目次を生成し、コメントの位置に挿入します。<!-- 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>を使用します。

カスタマイズ例

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

astro.config.mjs
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
});

まとめ

astro-custom-tocは、Astroで任意の場所に任意の構造の目次を生成するためのAstro integrationです。remark-tocとは異なり、目次の位置や構造を自由に変更できます。

バグなどがあればGitHubのissueまでお願いします。

Twitterのアイコン LINEのアイコン Threadsのアイコン Misskeyのアイコン Misskeyのアイコン
著者のアイコン画像

生まれた時から、母国語よりも先にJavaScriptを使っていました。ネットの海のどこにもいなくてどこにでもいます。

Webフロントエンドプログラマーで、テクノロジーに関する話題を追いかけています。動画編集やプログラミングが趣味で、たまにデザインなどもやっています。