markdown 语法最全汇总

判断标准：一份 Markdown 是否可维护，取决于是否区分 CommonMark 基础语法与 GFM 扩展语法。日常写作建议以 CommonMark 为底线，只有在 GitHub、GitLab、Notion 等明确支持 GFM 的环境，才使用表格、任务列表、删除线等扩展。

一、标题与段落

标题用 `#` 到 `######`。一篇文档通常只保留一个一级标题，正文内从二级标题开始，不要跳级。段落间用空行分隔；Markdown 中单个换行在多数渲染器里会被当作空格，要另起一段必须空一行。

• 判断：如果文章标题已由后台单独保存，正文不要再写一级标题。
• 步骤：二级标题写作 `## 一、标题与段落`；段落之间空一行。
• 注意：不要用连续空格或 Tab 模拟缩进，容易在不同渲染器中失控。

二、强调、引用与链接

粗体用 `文本`，斜体用 `文本` 或 `_文本_`。重点优先用粗体，斜体只用于术语、书名或轻微区分；同一段落不要大量使用。引用用 `>`，适合提示、摘录或风险说明，可以嵌套。 链接行内式：`[文字](url "可选标题")`。链接文字应能独立理解，不要写“点击这里”。参考式链接适合同一地址被多次引用的情况。

• 判断：链接是否在新标签打开由平台决定，不应在语法层承诺。
• 注意：URL 含空格或特殊字符时，需用 `<>` 包裹或进行百分号编码。

三、列表与任务列表

无序列表统一用 `-`，有序列表用 `1.`、`2.`。嵌套列表缩进 2 到 4 个空格，前后留空行。列表项内如果有多段内容，后续段落需要同样缩进。 任务列表是 GFM 扩展：

• [ ] 待办事项
• [x] 已完成事项
• 适用场景：任务列表适合议题、PR 描述、个人计划；正式文档慎用。
• 判断：并非所有平台支持任务列表，不支持时会退化为普通列表。
• 注意：有序列表的起始数字通常会被重新编号，不要依赖手写序号表达顺序。

四、代码与代码块

行内代码用反引号包裹，例如 `print("hello")`。代码块用三个反引号并标注语言： python print("hello") 若代码块内需要出现反引号，可以增加围栏反引号数量。

• 判断：语言标注不是强制，但能启用语法高亮，降低阅读成本。
• 步骤：复制代码后，第一行写 ` ```python `，最后一行写 ` ``` `。
• 注意：围栏式代码块是 CommonMark 基础语法；缩进式代码块也可用，但常与列表缩进冲突，不建议混用。

五、表格

GFM 表格写法： | 语法 | 作用 | 支持 | | --- | :---: | --- | | `#` | 标题 | CommonMark | | `- [ ]` | 任务 | GFM | 第二行分隔线用 `---` 控制列，冒号控制对齐。单元格内竖线需转义为 `\|`。

• 适用场景：表格适合小规模、结构固定的数据；不适合大段文字或复杂嵌套。
• 判断：表格是 GFM 扩展，在 CommonMark 环境可能原样显示，不渲染。
• 注意：列数必须一致，否则解析错乱；单元格内不能包含块级元素。

六、图片与转义

图片行内式：``。替代文字应描述内容，不能为空或只写“图片”。图片地址需可访问；相对路径依赖发布位置。 转义用反斜杠：`\不是强调\`。需要显示 Markdown 符号本义时，对 `*`、`_`、`#`、`\`、`` ` `` 等使用 `\`。

• 判断：图片无法显示时，替代文字是最后兜底，需要准确。
• 注意：不要用 Markdown 做复杂图文混排，它不是排版工具。

结尾小结

日常写作可以固定一个最小集合：标题、段落、粗体、链接、无序列表、有序列表、行内代码、围栏代码块、引用。只有在明确支持 GFM 的环境中，才使用表格、任务列表和删除线。发布前检查四项：标题是否跳级；表格列数是否一致；代码块语言是否写错；链接和图片是否可访问。