この Lua フィルタは、指定された Markdown ファイルが存在する階層以下の Markdown ファイルから、自動的に目次リストを生成し、対象ファイルに挿入します。
生成される目次は以下の形式で出力されます：
📄 [ファイル名](パス) <br/> 説明文📁 [フォルダ名](パス) <br/> 説明文📁 フォルダ名ファイル名/フォルダ名がリンクテキストとして表示され、Markdown ファイル内の最初の見出し（# タイトル）が説明文として表示されます。
Pandoc Lua フィルタの慣例に従い、\toc コマンドを使用します。
\toc\toc depth=1 exclude="temp.md" exclude="draft/*" exclude-basedir=true\newpage, \pagebreak 等の既存 Pandoc コマンドと一貫性を持ちます。現在のディレクトリ/
+-- index.md # 階層0 (自身、目次挿入対象)
+-- file1.md # 階層0 (現在のディレクトリ)
+-- subfolder1/ # 階層1 (1階層下)
| +-- file2.md # 階層1
| +-- subsubfolder/ # 階層2 (2階層下)
| +-- file3.md # 階層2
+-- subfolder2/ # 階層1 (1階層下)
+-- file4.md # 階層1指定方法を次に示す。
depth=0: 現在のディレクトリのみ (デフォルト)depth=1: 現在のディレクトリ + 1階層下までdepth=2: 現在のディレクトリ + 2階層下までdepth=-1: 制限なし (全階層を掘り下げ)指定方法を次に示す。
\toc exclude="temp.md" # 単一ファイル除外
\toc exclude="draft/*" # パターン除外
\toc exclude="temp.md" exclude="draft/*" # 複数除外除外パターン例を次に示す。
"README.md": 特定ファイル"draft/*": ディレクトリ配下全て"*.tmp": 拡張子による除外"temp.md": 特定ファイル名目次生成の起点となるディレクトリを指定します。指定しない場合は、\toc コマンドが記述されているファイルの存在するディレクトリが起点となります。
指定方法を次に示す。
\toc basedir="docs" # 現在のディレクトリからの相対パス
\toc basedir="docs/api" # サブディレクトリを指定
\toc basedir="../other" # 親ディレクトリからの相対パス\toc コマンドが記述されているファイルの存在するディレクトリからの相対パスプロジェクトルートの index.md から、docs/ サブディレクトリ以下の目次を生成する場合:
project/
+-- index.md # \toc basedir="docs" を記述
+-- README.md
+-- docs/
+-- guide.md
+-- api/
+-- reference.mdindex.md 内で以下のように記述:
\toc basedir="docs" depth=-1生成される目次:
- 📄 [guide.md](docs/guide.md) <br/> ガイド
- 📁 [api](docs/api/index.md) <br/> API
- 📄 [reference.md](docs/api/reference.md) <br/> リファレンス注意: 生成されるリンクは、\toc コマンドが記述されているファイルからの相対パスになります。
目次生成時に、基準ディレクトリ自体を目次から除外し、直下のファイル/フォルダを第一階層として表示します。
指定方法を次に示す。
\toc depth=-1 exclude-basedir=truedocs-src/README.md で以下のように記述した場合:
## 関連ドキュメント
\toc depth=-1 exclude="doxybook2/*" exclude-basedir=trueexclude-basedir=false (デフォルト):
- 📁 [docs-src](index.md) <br/> Document of c-modernization-kit
- 📄 [about-modern-development.md](about-modern-development.md) <br/> レガシー C コードにモダン手法を適用する全体像
- 📄 [build-design.md](build-design.md) <br/> クロスプラットフォームビルドシステムの実装exclude-basedir=true:
- 📄 [about-modern-development.md](about-modern-development.md) <br/> レガシー C コードにモダン手法を適用する全体像
- 📄 [build-design.md](build-design.md) <br/> クロスプラットフォームビルドシステムの実装Lua フィルタ内で定義されるデフォルト値は以下の通りです。
local defaults = {
depth = 0, -- 現在のディレクトリのみ
exclude = {}, -- 除外なし
basedir = "", -- 起点ディレクトリ指定なし（現在のディレクトリ）
["exclude-basedir"] = false -- 基準ディレクトリを除外しない
}\toc実行結果 (現在のディレクトリのみ)。
- 📄 [chapter1.md](chapter1.md) <br/> Chapter 1: イントロダクション
- 📄 [chapter2.md](chapter2.md) <br/> Chapter 2: 基本操作出力形式:
- ファイル/フォルダ名をリンクテキストとして表示
- <br/> (5つの ) の後に Markdown ファイル内の見出し（説明文）を表示
\toc depth=1実行結果。
index.md または index.markdown が存在する場合は、階層名に index.md または index.markdown へのリンクが生成される。そうでない場合は、階層名はリンクなし項目となる。
ファイル優先順位：
index.md > index.markdownINDEX.md → index.mdとして処理)階層名の表示ロジック：
# タイトル を説明文として表示
- 📄 [intro.md](intro.md) <br/> イントロダクション
- 📁 [tutorial](tutorial/index.md) <br/> チュートリアル
- 📄 [basics.md](tutorial/basics.md) <br/> 基本操作
- 📄 [advanced.md](tutorial/advanced.md) <br/> 応用
- 📁 reference
- 📄 [api.md](reference/api.md) <br/> API リファレンス
## 詳細## 現在のディレクトリ
\toc depth=0
## 全体構造
\toc depth=-1
## チュートリアルのみ
\toc depth=1 exclude="reference/*" exclude="intro.md"
## docs ディレクトリ以下のすべて
\toc basedir="docs" depth=-1
## API リファレンス（別ディレクトリ指定 + 除外）
\toc basedir="docs/api" depth=-1 exclude="internal/*"
## 関連ドキュメント（基準ディレクトリを除外）
\toc depth=-1 exclude="doxybook2/*" exclude-basedir=truepandoc -L index-filter.lua index.md -o output.htmlpandoc -L index-filter.lua --verbose index.md -o output.htmlinsert-toc.sh は性能向上のため、ファイル情報と Markdown タイトルをキャッシュファイルに永続化します。
/tmp/insert-toc-cache.tsv各行は以下の 5 つのフィールドをタブで区切った構造です。
絶対パス ファイル名 種別 ベースタイトル 言語別タイトルfile または directory言語コード:タイトル の形式、複数言語は | で区切り/home/user/docs/intro.md intro.md file intro ja:イントロダクション
/home/user/docs/tutorial tutorial directory tutorial
/home/user/docs/tutorial/basics.md basics.md file basics ja:基本操作
/home/user/docs/tutorial/index.md index.md file index ja:チュートリアル.md, .markdown）のみ# タイトル）を採用ja（日本語）固定ディレクトリのタイトルは以下の優先順位で解決されます。
index.md > index.markdown の順で検索INDEX.md → index.md）