Remark TOCで目次を作成
remark-tocを使用してmarkdownの目次を自動生成する方法を学び、ドキュメントを読みやすくナビゲート可能にしましょう。
多数の見出しを持つ長いmarkdownドキュメントを書き、手動で目次を作成したことはありますか?新しい見出しを追加するたびに、リンクのリストを手動で更新しなければならないのは大変ですよね?🤔
この記事では、remark-toc - markdownの目次(TOC)を簡単に自動生成できるプラグインを紹介します。
なぜ目次が必要なのか?#
目次のない500ページの本を読むことを想像してください。特定のトピックに関する情報を見つけたいのに、ページをめくって探さなければなりません。非常に疲れるし時間がかかりますよね?
技術ドキュメントでも同様の問題が発生します:
- 多くの見出しを持つ長いドキュメント
- 特定のコンテンツを見つけるのが難しい
- 読者がナビゲートするのに時間を浪費
- 手動更新は労力がかかる
remark-tocはこの問題を解決します:
- 自動化 - 既存の見出しからTOCを作成
- 自動更新 - 見出しを追加/編集すると、TOCが自動的に更新
- 高度なカスタマイズ - 深さ、見出しのスキップなどを設定可能
- 簡単な統合 - unified/remarkパイプラインで動作
Remark-tocはどのように動作しますか?#
remark-tocを知的な「司書」と考えてください。markdownドキュメントを渡すと:
- 特別な見出し(デフォルトは「Contents」または「TOC」)を見つける
- その後のすべての見出しを分析
- 各見出しへのリンクのリストを作成
- TOC見出しと次の見出しの間のコンテンツを置換
Remark-tocのインストール#
前提条件#
remark-tocはunified/remarkプラグインなので、以下が必要です:
- Node.js 16+
- npmまたはyarn
- unifiedまたはremarkがインストール済み
インストール#
npm install remark-tocbashyarn add remark-tocbashpnpm add remark-tocbash[!TIP] remark-tocはESM onlyなので、プロジェクトがESモジュールを使用していることを確認してください。
基本的な使用法#
シンプルな例#
example.mdファイルがあるとします:
# 冥王星
冥王星はカイパーベルトにある準惑星です。
## 目次
## 歴史
### 発見
1840年代、アーバン・ル・ヴェリエはニュートン力学を使用して...の位置を予測しました
### 名前と記号
冥王星の名前は冥界のローマ神ハデスのギリシャ語のエピテットから...
### 追加情報
冥王星に関する追加情報...
## 軌道
冥王星の公転周期は約248年です...markdownそして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実行後の結果:
# 冥王星
冥王星はカイパーベルトにある準惑星です。
## 目次
* [歴史](#歴史)
* [発見](#発見)
* [名前と記号](#名前と記号)
* [追加情報](#追加情報)
* [軌道](#軌道)
## 歴史
### 発見
1840年代、アーバン・ル・ヴェリエはニュートン力学を使用して...の位置を予測しました
### 名前と記号
冥王星の名前は冥界のローマ神ハデスのギリシャ語のエピテットから...
### 追加情報
冥王星に関する追加情報...
## 軌道
冥王星の公転周期は約248年です...markdown設定オプション#
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を作成:
await remark()
.use(remarkToc, {ordered: true, tight: false})
.process(file)js結果:
1. [歴史](#歴史)
1. [発見](#発見)
2. [名前と記号](#名前と記号)
2. [軌道](#軌道)markdown見出し深度の制限#
特定の深度までの見出しのみを含める:
await remark()
.use(remarkToc, {maxDepth: 3})
.process(file)jsこれにより、TOCにH1、H2、H3見出しのみが含まれます。
特定の見出しのスキップ#
TOCから不要な見出しを除外:
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プラグインとよく動作します:
rehype-slugとrehype-autolink-headingsと共に#
HTMLでクリック可能なTOCを作成:
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完全なパイプライン#
Next.jsでの使用#
next.config.mjsと共に#
import remarkToc from 'remark-toc'
import remarkGfm from 'remark-gfm'
const nextConfig = {
experimental: {
mdxRs: true,
},
mdxOptions: {
remarkPlugins: [
remarkGfm,
[remarkToc, {heading: 'Contents', maxDepth: 3}]
],
},
}
export default nextConfigjsMDXコンポーネントと共に#
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'}]]
}
}}
/>
)
}jsxAstroでの使用#
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を使用 - ユーザー入力を信頼しない
import rehypeSanitize from 'rehype-sanitize'
await remark()
.use(remarkToc)
.use(remarkRehype)
.use(rehypeSanitize) // HTMLをサニタイズ
.use(rehypeStringify)
.process(file)jsベストプラクティス#
1. 見出しの配置#
TOC見出しを適切な位置に配置 - 通常はイントロの後:
# タイトル
簡単な紹介...
## 目次
## セクション1markdown2. 合理的な深度#
maxDepthを深く設定しすぎない - 通常3-4で十分:
// 良い
{maxDepth: 3}
// 深すぎる、TOCが乱雑
{maxDepth: 6}js3. 不要な見出しのスキップ#
「References」、「Appendix」などの見出しをスキップ:
{skip: 'References|Appendix|Acknowledgments'}js4. Tight vs Loose#
tight: true技術ドキュメント向け(コンパクト)tight: false多くのテキストがあるドキュメント向け(読みやすい)
他のソリューションとの比較#
| 機能 | remark-toc | 手動TOC | TOCジェネレーター |
|---|---|---|---|
| 自動化 | あり | なし | あり |
| 自動更新 | あり | なし | あり |
| 高度なカスタマイズ | あり | あり | 制限あり |
| Remark統合 | あり | なし | なし |
| メンテナンス | あり | N/A | 変動 |
結論#
remark-tocは長いmarkdownドキュメントを書く人にとって有用なツールです。以下の助けになります:
- 見出しからTOCを自動作成
- メンテナンス労力を削減
- 柔軟なカスタマイズ
- unifiedエコシステムとの簡単な統合
[!TIP] ベストプラクティス:クリック可能なリンク付きの完全なTOCを得るために、常にremark-tocをrehype-slugとrehype-autolink-headingsと共に使用してください。