251202-mdtoc

README

mdtoc

Markdown TOC 生成工具，为 Markdown 文件自动生成符合规范的目录（Table of Contents）。

Table of Contents

• 功能特性 :21+9
• 安装 :30+10
• 使用示例 :40+26
• 命令选项 :66+15
• 开发 :81+18
  • 环境准备 :83+10
  • 构建 :93+6
• 参考项目 :99+7
• 相关链接 :106+4

功能特性

• 生成 GitHub 风格的 Table of Contents
• 支持 <!--TOC--> 标记定位，原地更新文件
• 默认只更新有标记的文件，-f 可强制生成
• 章节模式：每个 H1 后生成独立子目录
• 支持 YAML Frontmatter（VitePress、Hugo 等）
• 多文件批量处理，支持管道输入

安装

# 从 GitHub 安装
go install github.com/lwmacct/251202-mdtoc@latest

# 本地构建安装
go install .

# 设置别名
ln -sfn ~/go/bin/251202-mdtoc /usr/local/bin/mdtoc
ln -sfn ~/go/bin/251202-mdtoc ~/.local/bin/mdtoc

使用示例

# 查看帮助
mdtoc --help

# 生成 TOC 到 stdout
mdtoc README.md

# 原地更新文件 (在 <!--TOC--> 标记处插入)
mdtoc -i README.md

# 显示文件路径 + 行号范围
mdtoc -p README.md
# 输出: - [标题](#标题) `README.md:1+10`

# 使用有序列表 + 指定层级
mdtoc -o -m 2 -M 4 README.md

# 多文件处理
mdtoc -i docs/*.md

# 管道输入 (从 stdin 读取文件列表)
fd -e md | mdtoc -i

命令选项

选项	短选项	说明
--min-level	-m	最小标题层级 (默认 1)
--max-level	-M	最大标题层级 (默认 3)
--in-place	-i	原地更新文件
--force	-f	强制生成 TOC，即使没有 <!--TOC--> 标记
--delete	-d	删除文件中的 TOC
--ordered	-o	使用有序列表
--line-number	-L	显示行号范围 :start+count (默认启用)
--path	-p	显示文件路径 path:start+count
--global	-g	全局模式 (默认为章节模式)
--anchor	-a	预览时显示锚点链接

开发

环境准备

# 安装 pre-commit hooks
pre-commit install

# 查看可用任务
task -a

构建

go build ./cmd/mdtoc/

参考项目

项目	语言	说明
md-toc	Python	TOC 生成
goldmark	Go	CommonMark 解析器

相关链接

• CommonMark Spec - Markdown 规范
• Taskfile - 任务管理