markdown语法一览图

Markdown 的核心价值在于：同一份源文件既能直接阅读，也能渲染为结构化文档。日常写作只需掌握标题、段落、强调、列表、引用、链接、代码和表格八类语法即可覆盖多数场景。复杂排版应优先确认目标平台是否支持，不要用 Markdown 模拟视觉排版。

标题与段落

适用场景：任何需要分节的文档，如 README、笔记、技术方案、接口说明。 判断标准：一级标题通常对应文档标题，正文主要分节从二级标题开始；若二级下需要细分类，再使用三级标题，不应从二级直接跳到四级。 操作步骤：先列出全部标题大纲，确认层级关系后再填充段落；段落之间用空行分隔，不要用连续空格或 Tab 模拟缩进。 注意事项：标题中尽量避免使用行内代码或链接，部分解析器会有差异；同一文档内标题风格保持一致。行尾两个空格或反斜杠可以强制换行，但普通段落更推荐直接空行分段，以减少渲染差异。

强调与引用

适用场景：突出关键结论、操作名称、风险提示，或引用外部说明。 判断标准：一屏内粗体不超过三四处，避免强调失效；斜体只用于术语、书名或轻微区分，不宜整句使用。 操作步骤：需要突出“必须做/禁止做”时，用粗体句首短语，例如 注意： 后再接说明，不要整段加粗。引用内容用 `>`，可嵌套，但超过两层会降低可读性。 选择建议：提示、风险、判据适合放在引用块中；关键结论适合粗体；术语和书名适合斜体。三种强调不要叠加使用。

列表与任务列表

适用场景：枚举步骤、配置项、检查项，或记录待办与完成状态。 判断标准：如果列表项内容超过三行且包含多个完整句子，应考虑改用小标题加段落，而不是继续用长列表。 操作步骤：无序列表统一用 `-`，有序列表用 `1.`、`2.`；同一层列表符号保持一致。嵌套列表缩进 2 到 4 个空格，前后留空行，避免与段落粘连。 注意事项：任务列表 `- [ ]` 和 `- [x]` 是 GFM 扩展语法，CommonMark 并不原生支持；发布到不支持的平台时会退化为普通列表。列表项内包含多个段落或代码块时，需要额外缩进，否则渲染会中断列表。

链接、图片与代码

适用场景：引用外部资源、插入示意图、给出命令或代码示例。 判断标准：链接文字应说明目标，不要使用“点击这里”；图片替代文字必须描述内容，不能为空或只写“图片”。 操作步骤：行内链接写作 `[文字](地址 "标题")`，标题可省略。引用式链接适合多处复用：正文写 `[文字][id]`，文末写 `[id]: url "标题"`。图片写作 ``。 代码规则：行内代码用反引号，代码块用三个反引号并标注语言，如 ` ```python `。反引号内的特殊字符不需要转义；代码块语言标注应与内容匹配，不确定时留空，不要标错。 注意事项：链接地址含空格或括号时用尖括号包裹，如 `<https://example.com/a b>`。发布前检查链接能否打开、图片是否显示。

表格与转义

适用场景：展示少量对比信息、参数说明、兼容性列表等结构化数据。 判断标准：表格适合短单元格和数据对比；长段落、列表或代码块不应放入单元格。 操作步骤：使用 GFM 表格，分隔行控制对齐：左对齐 `:---`、右对齐 `---:`、居中 `:---:`。表头列数必须与分隔行列数一致，单元格内出现竖线写成 `\|`。 注意事项：需要显示 Markdown 符号本身时用反斜杠转义，如 `\*`、`\_`、`\#`。复杂表格建议改用 HTML 或直接说明“详见表格文件”，不要强行用 Markdown 嵌套列表或代码块。

小结

日常使用建议遵循“最小语法集 + 目标平台确认”。写作完成后重点检查：标题是否跳级、代码块语言是否正确、表格列数是否一致、列表缩进是否错乱、链接地址是否可访问、图片替代文字是否缺失。遇到 CommonMark 与 GFM 差异时，以发布平台实际支持为准；不要把 Markdown 当作可视化排版工具使用。