blog.dopana

戻る

多数の見出しを持つ長いmarkdownドキュメントを書き、手動で目次を作成したことはありますか?新しい見出しを追加するたびに、リンクのリストを手動で更新しなければならないのは大変ですよね?🤔

この記事では、remark-toc - markdownの目次(TOC)を簡単に自動生成できるプラグインを紹介します。

なぜ目次が必要なのか?#

目次のない500ページの本を読むことを想像してください。特定のトピックに関する情報を見つけたいのに、ページをめくって探さなければなりません。非常に疲れるし時間がかかりますよね?

技術ドキュメントでも同様の問題が発生します:

  1. 多くの見出しを持つ長いドキュメント
  2. 特定のコンテンツを見つけるのが難しい
  3. 読者がナビゲートするのに時間を浪費
  4. 手動更新は労力がかかる

remark-tocはこの問題を解決します:

  • 自動化 - 既存の見出しからTOCを作成
  • 自動更新 - 見出しを追加/編集すると、TOCが自動的に更新
  • 高度なカスタマイズ - 深さ、見出しのスキップなどを設定可能
  • 簡単な統合 - unified/remarkパイプラインで動作

Remark-tocはどのように動作しますか?#

remark-tocを知的な「司書」と考えてください。markdownドキュメントを渡すと:

  1. 特別な見出し(デフォルトは「Contents」または「TOC」)を見つける
  2. その後のすべての見出しを分析
  3. 各見出しへのリンクのリストを作成
  4. TOC見出しと次の見出しの間のコンテンツを置換
Markdownドキュメントremark-tocプラグインTOC見出しを検索後の見出しを分析リンクリストを作成TOCコンテンツを置換完全なTOC付きMarkdown

Remark-tocのインストール#

前提条件#

remark-tocはunified/remarkプラグインなので、以下が必要です:

  • Node.js 16+
  • npmまたはyarn
  • unifiedまたはremarkがインストール済み

インストール#

npmでインストール
npm install remark-toc
bash
yarnでインストール
yarn add remark-toc
bash
pnpmでインストール
pnpm add remark-toc
bash

[!TIP] remark-tocはESM onlyなので、プロジェクトがESモジュールを使用していることを確認してください。

基本的な使用法#

シンプルな例#

example.mdファイルがあるとします:

そしてexample.jsファイル:

example.js
import {remark} from 'remark'
import remarkToc from 'remark-toc'
import {read} from 'to-vfile'

const file = await remark()
  .use(remarkToc)
  .process(await read('example.md'))

console.log(String(file))
js

実行後の結果:

設定オプション#

remark-tocはカスタマイズのための多くのオプションを提供します:

オプションで設定
await remark()
  .use(remarkToc, {
    heading: 'Contents',      // 検索する見出し(デフォルト: '(table[ -]of[ -])?contents?|toc')
    maxDepth: 3,              // 最大見出し深度(デフォルト: 6)
    skip: 'References',       // 特定の見出しをスキップ
    tight: true,              // リストをtightにするかlooseにするか(デフォルト: true)
    ordered: false,           // 順序付きリストか順序なしリストか(デフォルト: false)
    prefix: 'user-content-'   // リンクのプレフィックス
  })
  .process(file)
js

高度な機能#

TOC見出しの変更#

「Contents」の代わりに別の見出しを使用したい場合:

別の見出しを使用
await remark()
  .use(remarkToc, {heading: 'Structure'})
  .process(file)
js

これにより、「Contents」の代わりに「Structure」見出し(大文字小文字を区別しない)が検索されます。

スペーシング付き順序付きリスト#

項目間にスペースがある番号付きリストとしてTOCを作成:

順序付きリストloose
await remark()
  .use(remarkToc, {ordered: true, tight: false})
  .process(file)
js

結果:

1. [歴史](#歴史)

   1. [発見](#発見)
   2. [名前と記号](#名前と記号)

2. [軌道](#軌道)
markdown

見出し深度の制限#

特定の深度までの見出しのみを含める:

深度を3に制限
await remark()
  .use(remarkToc, {maxDepth: 3})
  .process(file)
js

これにより、TOCにH1、H2、H3見出しのみが含まれます。

特定の見出しのスキップ#

TOCから不要な見出しを除外:

References見出しをスキップ
await remark()
  .use(remarkToc, {skip: 'References|Acknowledgments'})
  .process(file)
js

「References」と「Acknowledgments」見出しはTOCに表示されません。

リンクにプレフィックスを追加#

セキュリティ上の理由でプレフィックスが必要な場合に便利:

プレフィックスを追加
await remark()
  .use(remarkToc, {prefix: 'user-content-'})
  .process(file)
js

結果:

* [歴史](#user-content-歴史)
  * [発見](#user-content-発見)
markdown

他のプラグインとの統合#

remark-tocは他のremark/rehypeプラグインとよく動作します:

HTMLでクリック可能なTOCを作成:

rehypeプラグインと統合
import {remark} from 'remark'
import remarkToc from 'remark-toc'
import remarkRehype from 'remark-rehype'
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypeStringify from 'rehype-stringify'

await remark()
  .use(remarkToc)                          // TOCを作成
  .use(remarkRehype)                       // Markdown → HTML
  .use(rehypeSlug)                         // 見出しにIDを追加
  .use(rehypeAutolinkHeadings)             // アンカーリンクを追加
  .use(rehypeStringify)                    // HTML → string
  .process(file)
js

完全なパイプライン#

Markdown入力remark-tocremark-rehyperehype-slugrehype-autolink-headingsHTML出力

Next.jsでの使用#

next.config.mjsと共に#

MDXコンポーネントと共に#

import remarkToc from 'remark-toc'
import {MDXRemote} from 'next-mdx-remote/rsc'

export default function Post({content}) {
  return (
    <MDXRemote
      source={content}
      options={{
        mdxOptions: {
          remarkPlugins: [[remarkToc, {heading: 'Contents'}]]
        }
      }}
    />
  )
}
jsx

Astroでの使用#

astro.config.mjsと共に#

astro.config.mjs
import { defineConfig } from 'astro/config'
import mdx from '@astrojs/mdx'
import remarkToc from 'remark-toc'

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [
      [remarkToc, {heading: 'Contents', maxDepth: 3}]
    ]
  }
})
js

セキュリティ上の考慮事項#

[!WARNING] remark-tocは既存のノードをTOCにコピーするため、markdownに悪意のあるコンテンツが含まれている場合、XSS攻撃につながる可能性があります。

危険な例:

## 目次

## Bravo<script>alert(1)</script>
markdown

結果:

- [Bravo<script>alert(1)</script>](#bravoscriptalert1script)
markdown

解決策:

  • 処理前にmarkdownをサニタイズ
  • HTMLに変換するときにrehype-sanitizeを使用
  • ユーザー入力を信頼しない
rehype-sanitizeでサニタイズ
import rehypeSanitize from 'rehype-sanitize'

await remark()
  .use(remarkToc)
  .use(remarkRehype)
  .use(rehypeSanitize)  // HTMLをサニタイズ
  .use(rehypeStringify)
  .process(file)
js

ベストプラクティス#

1. 見出しの配置#

TOC見出しを適切な位置に配置 - 通常はイントロの後:

# タイトル

簡単な紹介...

## 目次

## セクション1
markdown

2. 合理的な深度#

maxDepthを深く設定しすぎない - 通常3-4で十分:

// 良い
{maxDepth: 3}

// 深すぎる、TOCが乱雑
{maxDepth: 6}
js

3. 不要な見出しのスキップ#

「References」、「Appendix」などの見出しをスキップ:

{skip: 'References|Appendix|Acknowledgments'}
js

4. Tight vs Loose#

  • tight: true 技術ドキュメント向け(コンパクト)
  • tight: false 多くのテキストがあるドキュメント向け(読みやすい)

他のソリューションとの比較#

機能remark-toc手動TOCTOCジェネレーター
自動化ありなしあり
自動更新ありなしあり
高度なカスタマイズありあり制限あり
Remark統合ありなしなし
メンテナンスありN/A変動

結論#

remark-tocは長いmarkdownドキュメントを書く人にとって有用なツールです。以下の助けになります:

  • 見出しからTOCを自動作成
  • メンテナンス労力を削減
  • 柔軟なカスタマイズ
  • unifiedエコシステムとの簡単な統合

[!TIP] ベストプラクティス:クリック可能なリンク付きの完全なTOCを得るために、常にremark-tocをrehype-slugとrehype-autolink-headingsと共に使用してください。

参考文献#