知识库格式规范与编译排错指南
本文档记录本工作区当前 Markdown 文档的严格格式要求,以及过去检查
docs/science/计算机考研/816/ 目录时发现的典型编译问题。
目标不是只让 Markdown 源码“能编译”,而是要保证编译后的页面没有裸 Markdown 符号、代码块误判、列表粘连、编号错乱或公式显示异常。
1. 当前编译环境
- 站点使用 Material for MkDocs。
- 数学公式由
pymdownx.arithmatex和 MathJax 处理。 - 公式配置为
generic: true,因此公式必须使用明确且成对的定界符。 - 页面还可能使用表格、任务列表、引用块、代码块和图表扩展。
- MkDocs 的默认目录排序生效;新增文档放入
docs/后会进入对应目录的导航。
2. 总体硬性要求
每篇新增或修改的文档都必须同时满足以下条件:
- Markdown 源码结构合法,不能依赖浏览器“碰巧”纠正错误。
- 编译后页面不能显示本应被解析的 Markdown 标记。
- 不能出现意外的
<pre><code>代码块。 - 列表、编号、标题、公式、表格和引用块必须保持正确的层级。
- 不仅检查首屏,还要检查全文中间和末尾的内容。
- 最终至少通过一次严格构建和一次差异空白检查。
3. 标题与段落
- 标题使用
#到######,并在#与标题文字之间保留一个空格。 - 标题前后应保留空行,避免标题与上一段或下一段粘连。
- 不要用连续的普通文本、全角空格或多个星号模拟标题。
- 每个独立语义段落之间保留一个空行。
- 题目、答案、结论、说明等内容应拆成独立段落,不要把大量内容堆在同一行。
- 需要分组时,优先使用标题或列表,不要只依赖数字前缀区分层次。
推荐:
## 题目
题目内容。
## 答案
答案内容。
不推荐:
## 题目
题目内容。答案:答案内容。补充:补充内容。
4. 列表与编号
4.1 基本规则
- 无序列表统一使用
-,后面保留一个空格。 - 有序列表使用
1.、2.等形式,后面保留一个空格。 - 同一层级的列表项必须使用一致的缩进。
- 子列表通常缩进 4 个空格;不要混用 3、5 或更多空格。
- 列表项较长或包含公式、代码块、引用块时,子内容必须保持在该列表项的缩进范围内。
- 列表前后保留空行,避免普通段落被错误合并到列表中。
- 连续编号的题目、步骤或答案应逐项换行,不能写成一整行。
- 编号重启时应明确分组;不要让多个独立题组共享一串连续编号。
推荐:
1. 第一项
2. 第二项
1. 第二项的子项
2. 第二项的另一个子项
3. 第三项
4.2 常见编译错误
- 子列表缩进不足:子项变成父项的普通文本。
- 子列表缩进过多:内容被识别成代码块,页面出现灰色背景或等宽字体。
- 列表项之间缺少空行:题目、答案和下一题粘连。
- 使用多个连续
*作为装饰:可能变成错误的强调标记或在页面中显示裸星号。 - 手写编号与 Markdown 有序列表混用:视觉上出现重复编号或编号错乱。
5. 粗体、斜体与星号
- 粗体使用成对的
**文字**。 - 斜体使用成对的
*文字*,但不要用孤立的*做装饰。 - 强调标记必须成对出现,不能出现
***、****等无法明确解析的组合。 - 乘法符号、通配符或其他字面星号必须根据语义转义或放入代码中。
- 修改后必须在编译页面的可见文本中搜索裸
*,不能只检查源码。
需要显示字面星号时:
使用反斜杠转义:\*
如果内容本身是代码或命令,应使用代码标记,而不是依赖转义:
`*`
6. 数学公式
6.1 公式定界符
- 行内公式使用成对的
$...$。 - 独立公式使用成对的
$$...$$,并将公式块放在顶层段落。 - 不允许只出现一个
$。 - 不允许把公式定界符拆到不同的普通段落中。
- 公式内部的美元符号必须转义或改写,不能破坏外层定界符。
6.2 嵌套列表中的公式
这是本工作区最容易产生编译残留的场景。深层列表中的 $$...$$ 可能被
Markdown 识别为缩进代码块,最终页面会显示原始 $ 或公式源码。
- 单行公式位于列表项中时,优先改为行内公式
$...$。 - 多行公式位于列表项中时,确认每一行的缩进与列表项一致,不要形成代码块。
- 复杂推导可以结束列表后单独成段,再使用顶层
$$...$$。 - 公式前后保留空行,避免与列表文字粘连。
推荐:
1. 路由器计算代价 $D_i = \min_j(D_j)$。
2. 计算结果为:
$$D_i = \min_j(D_j)$$
如果浏览器中出现裸 $、原始 $$、公式源码或灰色等宽代码块,应优先
检查公式所在列表的缩进,而不是盲目删除美元符号。
7. 反斜杠与转义
- 反斜杠只能用于明确的 Markdown 转义或公式命令。
- 不要在普通中文文本前随意添加
\。 - 命令参数、路径和代码应放入反引号代码标记或围栏代码块。
\~、\*、\[等转义写法必须在编译页面确认实际显示效果。- 如果反斜杠在页面中可见,说明它没有达到预期的转义效果,应改用正确的 Markdown 写法或代码标记。
8. 任务列表与方括号
- 真正的待办项使用
- [ ] 待办事项或- [x] 已完成事项。 - 普通说明中的
[ ]、[x]、[答案]等文本不要伪装成任务列表。 - 表格、代码块、协议字段和原始题目中的方括号应保留其语义。
- 修改方括号前必须结合上下文判断,不能全局替换。
- 编译后若普通段落中出现孤立的
[ ],应回到源码确认它是任务列表还是 遗留标记。
9. 代码块、引用块与表格
- 围栏代码块使用成对的三个反引号,并尽量注明语言。
- 代码块前后保留空行。
- 代码块内的 Markdown、美元符号、星号和方括号按代码原样保留,不应被当作
页面格式错误;检查时要区分
<pre><code>内外的内容。 - 引用块的每一行使用
>,不要让引用内容意外延伸到后续普通段落。 - 表格每一行列数应一致,分隔线必须存在。
- 公式、列表或代码块嵌入表格时,应优先确认编译页面布局;复杂内容最好移出表格。
10. 编译后的重点检查
检查不能只看源文件。必须对生成页面检查以下可见异常:
- 裸
$、$$或未闭合公式; - 裸
*、错误的***或****; - 不应出现的反斜杠;
- 普通正文中残留的
[ ]或[x]; - 公式源码显示为普通文本;
- 公式、列表或答案显示为灰色等宽代码块;
- 题目、序号、答案和段落粘成一坨;
- 有序列表编号重复、跳号或层级错乱;
- 本应是子列表的内容变成顶层列表;
- 标题、表格、引用块或代码块没有正确闭合。
检查时应排除以下正常内容,避免误报:
<code>和<pre>中作为代码展示的符号;- MathJax 或
arithmatex容器中的公式源码; - 题目正文明确要求展示的 Markdown 或协议符号。
11. 推荐排错流程
发现页面异常时,按以下顺序处理:
- 定位浏览器中异常文字所在的页面和章节。
- 在对应 Markdown 源文件中搜索该文字及其前后 20 行。
- 判断根因属于段落、列表缩进、公式定界符、强调标记、转义还是代码块。
- 优先修复源 Markdown,不要直接修改
site/下的编译产物。 - 重新编译后检查同一位置,再扫描全目录,防止同类错误残留。
- 对含大量公式或嵌套列表的页面进行浏览器视觉抽查。
- 最后运行完整验证命令。
不要使用以下高风险做法:
- 全局删除所有
$、*或反斜杠; - 只以
mkdocs build成功作为格式正确的依据; - 只检查一个文件或首屏;
- 把所有
[ ]都改成任务列表; - 直接编辑
site/生成结果来掩盖源码问题。
12. 提交前验证命令
在仓库根目录执行:
mkdocs build --strict --clean
git diff --check
其中:
mkdocs build --strict --clean用于确认全站可以从干净的输出目录严格编译。git diff --check用于发现行尾空格、空白错误和冲突标记等问题。
构建通过后,还应对生成的 site/ 页面做可见文本扫描,并在浏览器中至少抽查:
- 公式较多的页面;
- 嵌套列表较多的页面;
- 含表格、代码块和引用块的页面;
- 本次修改涉及的页面;
- 目录中其他可能使用相同模板或复制内容的页面。
13. 新文档最小自检清单
提交新文档前逐项确认:
- 标题层级正确,标题前后有空行。
- 普通段落没有大段粘连。
- 列表缩进统一,子列表使用 4 个空格。
- 编号没有重复、跳号或跨题组串联。
- 粗体、斜体和其他星号标记均成对闭合。
- 公式
$...$或$$...$$均成对出现。 - 列表中的公式没有被编译成代码块。
- 反斜杠只出现在有明确语义的位置。
-
[ ]只用于真正的任务列表或有意展示的文本。 - 代码块、引用块和表格均正确闭合。
- 严格构建通过。
-
git diff --check通过。 - 编译后的页面没有裸 Markdown 符号或明显布局异常。