更新:

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

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

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

これは何?

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

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

index.md
---
showToc: true
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- toc -->
## hoge
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.
### fuga
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

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

index.html
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</p>
<aside class="toc">
<h2>Contents</h2>
<nav>
<ul>
<li>
<a href="#hoge">hoge</a>
</li>
<ul>
<li><a href="#fuga">fuga</a></li>
</ul>
</ul>
</nav>
</aside>
<h2 id="hoge">hoge</h2>
<p>
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.
</p>
<h3 id="fuga">fuga</h3>
<p>
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</p>

他のプラグインとの違い

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

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

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

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

index.html
<aside class="toc">
<h2>目次</h2>
<nav>
<ul>
<li>
<a href="#hoge">hoge</a>
</li>
<ul>
<li><a href="#fuga">fuga</a></li>
</ul>
</ul>
</nav>
</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
import { defineConfig } from "astro/config";
import customToc from "astro-custom-toc";
// https://astro.build/config
export default defineConfig({
// ... other config
integrations: [
customToc()
]
});

使い方

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

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

index.md
---
showToc: true
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<!-- toc -->
## hoge
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を返す関数です。これを使用して、目次をカスタムテンプレートでラップできます。

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

const defaultTemplate = (html) => {
return `
<aside class="toc">
<h2>Contents</h2>
<nav>
${html}
</nav>
</aside>`.trim();
};

maxDepth

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

ordered

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

カスタマイズ例

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

astro.config.mjs
import { defineConfig } from "astro/config";
import customToc from "astro-custom-toc";
const tocTemplate = (html) => {
return `
<aside class="toc">
<h2>目次</h2>
<nav>
${html}
</nav>
</aside>`.trim();
};
// https://astro.build/config
export default defineConfig({
// ... other config
integrations: [
customToc({
template: tocTemplate
}),
mdx()
]
});

まとめ

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

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

#Astro#GitHub#JavaScript#Markdown#Web開発#オープンソース
Xに共有する Blueskyに共有する Misskeyに共有する LINEに共有する Threadsに共有する

おすすめアイテム

※このリンクを経由して商品を購入すると、当サイトの運営者が報酬を得ることがあります。詳細はこちら

著者のアイコン画像

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

Webフロントエンドプログラマーで、テクノロジーに関する話題を追いかけています。動画編集やプログラミングが趣味で、たまにデザインなどもやっています。主にTypeScriptを使用したWebフロントエンド開発を専門とし、便利で実用的なブラウザー拡張機能を作成しています。また、個人ブログを通じて、IT関連のニュースやハウツー、技術的なプログラミング情報を発信しています。