markdown 语法手册 完整整理版

Markdown 没有单一“官方完整版”，实用中应以 CommonMark 作为兼容基线，把 GFM（GitHub Flavored Markdown）作为常用扩展。判断一份 Markdown 是否合格，先看三点：块级元素是否用空行分隔、行内与块级符号后是否留空格、扩展语法是否在目标平台受支持。满足这三条，即可避免大多数解析不一致问题。

一、块级结构：标题、段落、列表与引用

标题从 `#` 到 `######`，一个文档只保留一个一级标题，后续从二级开始，避免跳级。写法为 `## 小节标题`，`#` 与文字之间必须有一个空格；不带空格时部分工具不会解析为标题。段落之间用空行分隔，不要用连续空格或 Tab 模拟缩进；CommonMark 中四空格缩进会被解析为代码块，容易造成误排版。 无序列表统一用 `-`，有序列表用 `1.`、`2.`，同一文档不要混用多种无序符号。嵌套列表缩进 2 到 4 个空格，前后留空行。引用用 `>`，适合放提示、摘录或风险说明；嵌套引用使用 `>>`。判断标准是：同一级内容符号列对齐，嵌套越深缩进越多。

二、行内格式与代码

重点优先用粗体 `文本`，斜体 `文本` 只用于术语、书名或轻微区分，中文正文中尽量少用斜体。不要整段加粗，否则会失去强调效果。行内代码用反引号包裹，例如 `git status`；如果代码内出现反引号，用双反引号包裹。代码块使用三个反引号并在起始行标注语言，如 `python`、`bash`，前后空行，语言标注应写实际语言名，便于高亮。

三、链接与图片

行内链接写为 `[文字](url "标题")`，标题可选。URL 包含空格或特殊字符时，建议使用 `<>` 包裹或进行百分号编码，避免断链。图片使用 ``，替代文字应描述图片内容而不是只写文件名；这既影响可读性，也影响无障碍访问。引用式链接适合重复引用同一地址，文章较短时不必使用。自动链接只有写在 `<>` 内才是 CommonMark 标准写法；裸 URL 是否自动识别取决于平台，发布前应验证。

四、GFM 扩展：表格与任务列表

表格和任务列表不属于 CommonMark，但在 GitHub、Hugo、多数笔记软件中受支持。表格使用 GFM 语法，分隔行用 `| --- | :---: |` 控制对齐；列数必须一致，单元格内出现的 `|` 要写成 `\|`。适合做参数对比、选项说明，不建议在单元格中放长段落。任务列表写为 `- [ ] 待办`、`- [x] 完成`，适合记录进度或验收项。使用前先确认目标平台支持，否则任务列表会退化为普通无序列表，表格会显示为未解析的竖线文本。

五、换行、分隔线与转义

CommonMark 中普通回车不产生换行，而是合并为空格；需要硬换行时，行末写两个空格或反斜杠 `\`，但两个空格容易在编辑时被删除，建议用段落分隔代替。分隔线使用三个及以上的 `---`，前后必须空行；注意 `---` 紧跟在文字下方会被解析为 Setext 二级标题，而不是分隔线。需要显示 Markdown 符号本身时，在符号前加反斜杠转义，例如 `\不是斜体\`。标题、列表、引用符号在同一行内需要作为普通文字出现时，也采用同样转义方式。

六、发布前检查清单

发布前按以下顺序检查：标题层级是否跳级；块级元素是否空行分隔；链接能否打开、图片是否显示；代码块语言标注是否正确；表格列数是否一致；列表缩进是否错乱；任务列表和表格在目标平台是否按预期渲染。若文档会在多个平台流转，优先保留 CommonMark 子集，扩展语法尽量集中使用并做降级说明。 掌握上述块级、行内、GFM 扩展与发布检查，就能覆盖绝大多数 Markdown 写作场景。实际使用中不必追求所有语法都用到，应根据阅读环境选择最小可用子集；不确定是否支持的扩展语法，用标准段落、列表或引用替代，通常比强行使用更稳妥。