mc-mdtoc

Appearance

mc-mdtocMarkdown TOC 生成工具

为 Markdown 文件自动生成符合规范的目录

快速开始
设计文档

GitHub 风格锚点

生成符合 GitHub 规范的 anchor link，支持中英文混合标题

章节模式

每个 H1 后生成独立子目录，适合长文档组织

Frontmatter 支持

自动跳过 YAML frontmatter，兼容 VitePress、Hugo 等

批量处理

支持多文件和管道输入，轻松集成到 CI/CD 流程

mc-mdtoc ​

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

Table of Contents ​

功能特性 ​

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

安装 ​

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

# 本地构建安装
go install ./cmd/mc-mdtoc

使用示例 ​

shell
# 查看帮助
mc-mdtoc --help

# 生成 TOC 到 stdout
mc-mdtoc README.md

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

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

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

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

# 管道输入 (从 stdin 读取文件列表)
fd -e md | mc-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预览时显示锚点链接

开发 ​

环境准备 ​

shell
# 安装 pre-commit hooks
pre-commit install

# 查看可用任务
task -a

构建 ​

shell
go build ./cmd/mc-mdtoc/

参考项目 ​

项目语言说明
md-tocPythonTOC 生成
goldmarkGoCommonMark 解析器

相关链接 ​