markdown使用手册

判断一份 Markdown 文档是否合格，可以看两条：在纯文本状态下是否易读；渲染后是否层次清楚、不产生歧义。日常写作优先使用 CommonMark 核心语法；需要表格、任务列表、删除线时，再使用 GitHub Flavored Markdown（GFM）扩展。以下按使用频率组织。

标题与段落

标题用 `#` 至 `######`，一级标题通常一个文档只出现一次。不要跳级：如果上一级是 `##`，下一级应为 `###`，而不是 `####`。 段落之间空一行；不要用连续空格或 Tab 模拟缩进。段落内换行需谨慎：CommonMark 中行尾加两个空格或反斜杠才会产生硬换行；GFM 中直接回车在多数渲染器里仍视为同一段落。 可执行建议：写完后用“标题大纲”视图检查层级是否连续，一级标题是否唯一。

强调、列表与引用

重点优先用粗体 `重点`；斜体 `术语` 只用于术语、书名或轻微区分。一屏内重点不要超过三处，否则失去强调效果。 无序列表统一用 `-`；有序列表用 `1.`、`2.`。嵌套列表缩进 2 到 4 个空格，前后留空行。 引用用 `>`，适合放摘录、提示、风险说明。可嵌套，但两层以上会显著降低可读性。 任务列表 `- [ ] 待办`、`- [x] 完成` 是 GFM 扩展，并非所有平台支持。如果发布到不支持的环境，会显示为普通列表，不会丢失内容，但完成状态不可用。 注意事项：不要在列表项之间随意插入未缩进的段落，否则会打断列表。嵌套列表的层级不要超过三级。

代码与链接、图片

行内代码用反引号包裹，如 `git status`。如果代码本身含反引号，用双反引号包裹。 代码块用三个反引号并标注语言，例如 ` ```python`。语言标识用于语法高亮，不决定代码能否运行；没有合适语言时写 `text` 或省略。 链接写法 `[文字](地址 "标题")`，标题可省略。地址含空格或特殊字符时用 `<...>` 包裹。GFM 支持自动链接，但显式写法更可控，建议在正式文档中显式写出链接文字。 图片写法 ``。替代文字必须描述图片内容，而不是只写“图片”；渲染失败时，替代文字是读者唯一获得的信息。 注意：相对路径在发布或移动文档后容易失效，尽量使用可长期访问的地址；本地图片在分享前需确认对方能访问。

表格与转义

GFM 表格的写法是：表头行、分隔行、内容行。分隔行用 `| --- | :---: |` 控制对齐，例如： | 项目 | 说明 | | :--- | :---: | | A | B | 表格适合小规模、结构化对比。超过 5 列或单元格内容较长时，在移动端和纯文本下可读性差，应改用定义列表或分项列表。 单元格内出现竖线写成 `\|`。表格外竖线通常不需要转义。 需要显示 Markdown 符号本身时，用反斜杠转义，如 `\*`、`\_`、`\#`。在代码块和行内代码中不要转义，否则会显示多余反斜杠。

平台差异与选择建议

纯 CommonMark：适合需要长期保存、跨系统迁移的基础文档，语法最小，行为最可预测。 GFM：适合 GitHub、GitLab、多数笔记软件和协作文档；支持表格、任务列表、删除线、自动链接等。 脚注、数学公式、目录、流程图等属于具体平台增强，不保证通用；一旦换平台可能失效。 选择建议：不确定目标平台时，只用 CommonMark 核心语法；确定在 GitHub 或同类平台发布时，再启用 GFM 表格和任务列表，并在发布前确认渲染效果。

发布前检查清单

• 标题层级是否连续；是否只有一个一级标题。
• 列表缩进是否一致；嵌套列表前后是否留空。
• 代码块语言标识是否正确；代码是否可复制、无隐藏空格。
• 链接和图片地址是否有效；图片替代文字是否描述内容。
• 表格列数是否一致；单元格内竖线是否已转义。
• 任务列表是否被目标平台支持；是否需要回退为普通列表。
• 是否存在多余的空格、Tab 或未转义符号。

Markdown 的价值在于“源文件即文档”：结构由符号表达，但不应牺牲纯文本可读性。日常写作先确定目标平台，只启用必要的扩展语法；发布前按清单检查一遍。如果需要生成正式公文、红头文件或精确分页排版，Markdown 不适合直接交付，应改用对应模板或排版工具。