Astroでカスタマイズ可能な目次を生成する「astro-custom-toc」
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.
— ろぼいん (@keita_roboin) March 3, 2024
初めてのAstro integrationを公開しました!🥳 Markdownのページにカスタマイズ可能な目次を生成します。
astro-custom-toc - npmhttps://t.co/RFDRF1qDhe
これは何?
astro-custom-tocは、Astroで任意の場所に任意の構造の目次を生成するためのAstro integrationです。MarkdownファイルとMDXファイルに対応しています。
たとえば、次のようなMarkdownファイルがあったとします。
このファイルに対して、次のように目次を生成できます。目次を挿入する箇所や目次の構造は、自由に変更できます。
他のプラグインとの違い
既存の主要なプラグインとしては、remark-tocがあります。remark-tocは、remark.jsのプラグインで、基本的な機能をすべて備えています。
しかし、remark-tocにはいくつかの制限があります。デフォルトでは、目次は「Contents」「Table of contents」「ToC」などの見出しの下に生成されます。
これによって目次の位置を調整できますが、目次の構造はカスタマイズできません。また、目次を示す見出しを挿入したくない場合もあります。
私は次のような構造の目次を任意の場所に挿入する方法を探していました。
これをremark-tocで実現するには、毎回<aside class="toc"></aside>
と<h2></h2>
を手動で挿入する必要があります。また、目次を<nav></nav>
で囲むのは(おそらく)不可能です。
このような問題を解決するために、任意の場所に任意の構造の目次を生成する「astro-custom-toc」を開発しました
インストール
ここからは、astro-custom-tocのインストール方法について説明します。
自動インストール
astro-custom-tocは、astro add
コマンドに対応しており、次のコマンドでインストールできます。
astro add
を使う場合は、このコマンドだけで最低限の設定が完了します。
手動インストール
何らかの理由でastro add
コマンドが使えない場合は、手動でインストールできます。
まず、次のコマンドでastro-custom-tocをインストールします。
次に、astro.config.mjs
にastro-custom-tocを追加します。
使い方
astro-custom-tocのインストールが完了したら、実際に使ってみましょう。astro-custom-tocは、MarkdownファイルとMDXファイルに対応しています。
見出しを生成するには、frontmatterにshowToc: true
を追加し、目次を挿入したい場所に<!-- toc -->
コメントを挿入します。
これで、astro-custom-tocが目次を生成し、コメントの位置に挿入します。<!-- toc -->
コメントが見つからない場合は、先頭に目次が挿入されます。
カスタマイズ
astro-custom-tocは、次のようなオプションを提供しています。
template
生成された目次のHTMLを受け取り、最終的なHTMLを返す関数です。これを使用して、目次をカスタムテンプレートでラップできます。
デフォルトのテンプレート関数:
maxDepth
生成される目次の最大の深さです。デフォルトは3
で、<h3>
までの見出しを目次に含めます。
ordered
目次を順序付きリスト(<ol>
)にするかどうかです。デフォルトはfalse
で、目次に<ul>
を使用します。
カスタマイズ例
私のブログでは、次のようなオプションを使用しています。
まとめ
astro-custom-tocは、Astroで任意の場所に任意の構造の目次を生成するためのAstro integrationです。remark-tocとは異なり、目次の位置や構造を自由に変更できます。
バグなどがあればGitHubのissueまでお願いします。