前置知识: Markdown

规范文档编写

6 min中级

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

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

知识点地图

本篇属于「工程化写作」知识类别，是表格（100）、脚注（150）、目录（200）、 锚点（190）几个单语法篇的组合应用篇。

解决什么问题：单篇语法都会用了，拼成一份几十行的规范文档（API 说明、 接口约定、部署手册）时，结构松散、出处不明、读者找不到章节。

什么时候用到：写任何「会被多人反复查阅」的文档之前；或者接手一份 别人写的文档，要判断它缺什么的时候。

三个真实使用场景：

  1. API 接口文档：参数表用表格对齐，错误码用脚注注明含义来源， 顶部目录让调用方直接跳到目标接口；
  2. 部署手册：步骤编号 + 交叉引用（「见第 3 节的回滚步骤」）， 出事故时按锚点直达对应小节；
  3. 团队编码规范：用一致性检查清单做发布前自检，术语写法统一 由 lint 工具兜底。

1. 表格进阶

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

1.1 对齐方式

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

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

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

1.2 单元格内换行

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

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

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

GFM 表格不支持合并单元格，确需合并时退回 HTML 表格（注意 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 单元格内的行内元素

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

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

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

2. 脚注

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

markdown
延迟测试显示 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），直接链接即可：

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

4.2 自定义锚点

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

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

4.3 跨文件引用

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

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

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

5. 文档结构规范

5.1 标题层级

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

## 章节（H2）

### 小节（H3）

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

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

5.2 元信息（frontmatter）

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

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

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

5.3 章节组织模板

markdown
## 1. 概述

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

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

## 4. 常见问题

## 5. 参考资料

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

6. 一致性检查清单

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

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

7. 动手实践

任务：把下面这段「原始素材」改写成符合本篇规范的文档片段： 补一个两列参数表（参数名左对齐、说明左对齐）、给两处需要出处的地方 加脚注、在段首加一条指向本文「文档结构规范」小节的页内交叉引用。

原始素材（故意只有裸文字）：

markdown
上传接口接收三个参数。file 是必填的文件对象。token 是必填的鉴权
令牌。expire 可选，单位秒，缺省 3600。expire 的默认值来自运维
手册第 12 页，token 的格式定义在鉴权白皮书里。

提示：表格里放参数名、必填性、说明三列更实用，说明列里可以 顺手放脚注标记；页内锚点写法见 markdown/190-AnchorLinks； GitHub 的标题 slug 是小写加连字符。

遮代码自检——先自己写，再对照：

参考实现（点开前先自己完成）
markdown
## 上传接口

[参数说明见「文档结构规范」小节](#5-文档结构规范)。

| 参数   | 必填 | 说明                                   |
| :----- | :--- | :------------------------------------- |
| file   | 是   | 待上传的文件对象                        |
| token  | 是   | 鉴权令牌，格式见[^token-spec]           |
| expire | 否   | 过期时间，单位秒，缺省 3600[^ops-manual] |

[^token-spec]: 令牌格式定义见《鉴权白皮书》v2.3 第 4 章。
[^ops-manual]: 默认值依据运维手册（2026-05 修订版）第 12 页。

对照要点：脚注标记跟在所修饰内容之后、句号之前更符合阅读节奏； 脚注定义写在哪里渲染时都会被收集到文档末尾，所以就近写不破坏表格 结构；页内锚点 #5-文档结构规范 是 GitHub 对 ## 5. 文档结构规范 的 slug 化结果——标题改动后锚点会失效，这正是第 4 节说「重要锚点 用显式 id」的原因。

小结

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