mdbook-toc 操作手册
mdbook-toc 用于在章节内部生成页内目录。它扫描 marker 后面的标题，并生成对应锚点列表。
原仓库：https://github.com/badboy/mdbook-toc
本页目录
上面的目录就是本插件根据本页标题生成的。
基础用法
默认 marker：
<!-- toc -->
把它放在希望显示目录的位置即可。
样例
# 向量检索系统设计
<!-- toc -->
## 背景
正文……
## 索引结构
### 上层索引
正文……
### 下层索引
正文……
## 实验
正文……
构建后 marker 会被替换成指向这些标题的页内目录。
marker 的位置
插件只根据 marker 后方的标题生成目录，所以通常应放在 H1 之后、第一个 H2 之前。
# 文章标题
简介。
<!-- toc -->
## 第一部分
...
如果把 marker 放在文章中间，前面的标题不会进入 TOC。
标题层级
目录层次直接来自 Markdown heading：
## 一级目录项
### 二级目录项
#### 三级目录项
不要为了字号效果随意跳标题级别，否则 TOC 结构也会混乱。
最大标题级别
默认包含到 H4。可以修改：
[preprocessor.toc]
max-level = 3
这样目录最多包含到 ###。
如果只想显示主要部分：
max-level = 2
自定义 marker
例如改成 GitLab 风格：
[preprocessor.toc]
marker = "[[_TOC_]]"
正文中就使用：
[[_TOC_]]
多行 marker
支持多行字符串，例如：
[preprocessor.toc]
marker = """* auto-gen TOC;
{:toc}"""
也可以写成：
[preprocessor.toc]
marker = "* auto-gen TOC;\n{:toc}"
当前书库配置
[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]
当前仅对 HTML renderer 运行。
什么时候使用
推荐用于长论文笔记、三级以上标题较多的技术文档、系统设计文档和操作手册。短页面通常不需要 TOC。
常见问题
某个标题没有进入目录
检查：
- 标题是否位于 marker 之前；
- 标题级别是否超过
max-level； - 是否使用了真正的 Markdown heading。
目录层级很乱
通常是正文标题跳级造成的。先修正文档标题结构，而不是单独调整 TOC。