跳转至

知识库格式规范与编译排错指南

本文档记录本工作区当前 Markdown 文档的严格格式要求,以及过去检查 docs/science/计算机考研/816/ 目录时发现的典型编译问题。

目标不是只让 Markdown 源码“能编译”,而是要保证编译后的页面没有裸 Markdown 符号、代码块误判、列表粘连、编号错乱或公式显示异常。

1. 当前编译环境

  • 站点使用 Material for MkDocs。
  • 数学公式由 pymdownx.arithmatex 和 MathJax 处理。
  • 公式配置为 generic: true,因此公式必须使用明确且成对的定界符。
  • 页面还可能使用表格、任务列表、引用块、代码块和图表扩展。
  • MkDocs 的默认目录排序生效;新增文档放入 docs/ 后会进入对应目录的导航。

2. 总体硬性要求

每篇新增或修改的文档都必须同时满足以下条件:

  1. Markdown 源码结构合法,不能依赖浏览器“碰巧”纠正错误。
  2. 编译后页面不能显示本应被解析的 Markdown 标记。
  3. 不能出现意外的 <pre><code> 代码块。
  4. 列表、编号、标题、公式、表格和引用块必须保持正确的层级。
  5. 不仅检查首屏,还要检查全文中间和末尾的内容。
  6. 最终至少通过一次严格构建和一次差异空白检查。

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. 推荐排错流程

发现页面异常时,按以下顺序处理:

  1. 定位浏览器中异常文字所在的页面和章节。
  2. 在对应 Markdown 源文件中搜索该文字及其前后 20 行。
  3. 判断根因属于段落、列表缩进、公式定界符、强调标记、转义还是代码块。
  4. 优先修复源 Markdown,不要直接修改 site/ 下的编译产物。
  5. 重新编译后检查同一位置,再扫描全目录,防止同类错误残留。
  6. 对含大量公式或嵌套列表的页面进行浏览器视觉抽查。
  7. 最后运行完整验证命令。

不要使用以下高风险做法:

  • 全局删除所有 $、* 或反斜杠;
  • 只以 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 符号或明显布局异常。