前置知识: Markdown

规范文档编写

5 min中级

编写规范技术文档的组合技巧：表格进阶、脚注、目录、交叉引用与文档结构约定。

认知导入（Layer 2 专业层） 前置知识：024 表格、009 脚注、019 自动目录（本篇是三者的”组合应用”篇）。 边界说明：本篇讲”怎么把多种语法组合成一份规范的技术文档”，单语法细节请查阅对应文档；所有示例以 GitHub/GFM 兼容为基准，个别写法标注了平台限制。 强制练习：给一段含表格与引用的技术说明补上脚注、目录与两处交叉引用，在 GitHub 预览验证全部跳转。

1. 表格进阶

基础表格语法见 markdown/100-Table，这里补充规范文档常用的四个技巧。

1.1 对齐方式

分隔行用冒号控制列对齐（: 在左、两侧、右侧分别对应左对齐、居中、右对齐）：

| 左对齐       |  居中对齐  |       右对齐 |
| :----------- | :--------: | -----------: |
| 左           |     中     |           右 |
| 长文本左对齐 | 长文本居中 | 长文本右对齐 |

数字列右对齐、文本列左对齐是常见约定；表头行源码里的空格只是排版美化，不影响渲染。

1.2 单元格内换行

表格单元格不能直接换行，用 <br> 标签：

| 项目  | 描述                       |
| ----- | -------------------------- |
| 功能A | 第一行<br>第二行<br>第三行 |

1.3 复杂表格（合并单元格）

GFM 表格不支持合并单元格，确需合并时退回 HTML 表格（注意 HTML 块前后留空行）：

<table>
  <thead>
    <tr>
      <th>模块</th>
      <th>名称</th>
      <th>默认值</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">数据库</td>
      <td>host</td>
      <td>localhost</td>
    </tr>
    <tr>
      <td>port</td>
      <td>5432</td>
    </tr>
  </tbody>
</table>

能不用就不用：HTML 表格维护成本高，且部分严格渲染环境会过滤属性。

1.4 单元格内的行内元素

代码、链接、加粗等行内元素在单元格内正常解析：

| 方法 | 语法            | 说明             |
| ---- | --------------- | ---------------- |
| 数组 | `Array.from()`  | 从类数组创建数组 |
| 对象 | `Object.keys()` | 获取键名数组     |

注意：任务复选框 [x]、竖线 | 等在单元格内有特殊含义或被当字面文本处理，表格内写竖线需转义为 \|。

2. 脚注

脚注语法详见 markdown/150-Footnote（GitHub 自 2021 年起支持）。规范文档中的典型用法——给结论附出处：

延迟测试显示 P99 低于 80ms[^bench]。

[^bench]: 基准测试报告 v3，测试环境与完整数据见仓库 `bench/` 目录。

要点：

  • 定义（[^名]: 内容）可放在文档任意位置，渲染时自动收集到文末并生成回链；
  • 标签名可用数字或短横线命名（[^study-2024]），渲染序号按引用顺序自动编排；
  • 同一脚注可被多处引用，多个引用点都会链接到同一条注释。

行内脚注 ^[直接写内容] 是 Pandoc 私有语法，GitHub 不支持，跨平台文档不要使用。

3. 目录

占位符目录语法是平台私有的，选型前先确认目标平台（详见 markdown/200-AutoTOC）：

平台写法
Typora[TOC]
VuePress / VitePress[[toc]]
Azure DevOps Wiki[[_TOC_]]
Jekyll / kramdown空列表项 + {:toc}
Pandoc构建参数 --toc
GitHub无占位符：用内置大纲面板，或手写锚点链接目录（可用 doctoc 等工具生成）

注意：网传”GitHub 风格 [[_TOC_]]”实为 Azure DevOps Wiki 的语法，GitHub 上只会原样显示。

4. 交叉引用

4.1 文档内标题锚点

渲染器为每个标题自动生成锚点（生成规则见 markdown/190-AnchorLinks），直接链接即可：

详见 [安装指南](#安装指南) 章节。

4.2 自定义锚点

需要稳定锚点（不随标题文字变化）时用 HTML 显式声明 id：

<a id="custom-anchor"></a>
跳转到 [自定义锚点](#custom-anchor)

4.3 跨文件引用

链接到同仓库其他文档时附上锚点，GitHub 会正常解析：

详见 [API 文档](./api-reference.md#认证) 中的认证章节。

注意跨文件锚点的 slug 规则以目标文件所在平台为准；仓库内移动或重命名文件时记得同步修复这些链接（可依赖 CI 的死链检查）。

5. 文档结构规范

5.1 标题层级

# 文档标题（H1，仅一个）

## 章节（H2）

### 小节（H3）

#### 细节（H4，尽量少用）

规则：每个文档只有一个 H1；不跳级（H2 直接到 H4 是错的）；H4 以下层级过深说明该拆分文档了。

5.2 元信息（frontmatter）

静态站点与文档工具依赖文件头部的 YAML 元数据（详见 markdown/260-FrontmatterYAML）：

---
title: 文档标题
description: 一句话描述
difficulty: intermediate
related:
  - markdown/030-ParagraphLineBreak
---

托管字段（order、author、updated 等）如果工具链会自动补全，就不要手写，避免双源维护。

5.3 章节组织模板

## 1. 概述

## 2. 基础概念
### 2.1 核心术语
### 2.2 工作原理

## 3. 实践指南
### 3.1 快速开始
### 3.2 进阶配置

## 4. 常见问题

## 5. 参考资料

组织原则：概述回答”这是什么、为什么要读”；概念先于操作；每个操作给出可验证的结果；“常见问题”收集排错路径，减少重复答疑。

6. 一致性检查清单

发布规范文档前逐项自检：

  • 标题层级连续、H1 唯一
  • 表格列数一致，含竖线的内容已转义
  • 脚注定义齐全、无未引用的孤立定义
  • 页内与跨文件链接逐个可跳转
  • frontmatter 字段符合仓库约定
  • 术语、命令写法全篇一致（可用 markdownlint 与拼写检查辅助）

小结

  • 初学者要点：表格对齐用分隔行的冒号控制，单元格换行用 <br>；脚注 [^名] 标注出处、定义自动收集到文末；GitHub 没有目录占位符，靠大纲面板或工具生成。
  • 进阶注意：[[_TOC_]] 是 Azure DevOps 语法不是 GitHub 的；行内脚注 ^[...] 是 Pandoc 私有；合并单元格需退回 HTML 表格且慎用；自定义锚点用显式 id 保证跨标题改动的稳定性；文档结构遵循”唯一 H1、不跳级、概念先于操作”。