markdown 语法文档

Markdown 的核心价值在于用最少标记表达结构化文本，适合文档、笔记、评论和 README。判断标准很直接：如果内容以标题、段落、列表、代码、链接和表格为主，且需要纯文本可读、版本可比较，优先使用 Markdown；如果需要精确分页、多栏排版或公文格式，应改用排版工具。

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

标题使用 `#` 至 `######`，一个文档通常只保留一个一级标题。建议从二级标题开始分节，逐级使用，不要跳级。段落之间用空行分隔；不要用连续空格或 Tab 模拟缩进。引用使用 `>`，可嵌套，适合放提示、摘录或风险说明： > 注意：多个连续行如果没有空行，会被合并为同一段落。 适用场景：README、说明文档、技术方案的开头部分。注意事项：标题后应有空格，例如 `## 二级标题`；部分平台会自动生成目录，层级混乱会影响跳转。

列表与任务

无序列表统一用 `-`，有序列表用 `1.`、`2.`。嵌套列表缩进 2 到 4 个空格，前后留空行。任务列表用 `- [ ]` 和 `- [x]`：

• 待办项
• 已完成项

任务列表属于 GFM 扩展，CommonMark 不保证支持。判断标准：如果读者需要在网页端勾选，使用任务列表；如果文档可能在纯文本环境阅读，优先使用普通列表。步骤：先写列表项，再在 `-` 后加 `[ ]` 或 `[x]`，注意方括号与文字之间留一个空格。

代码与行内标记

行内代码用反引号包裹，例如 `git status`。代码块用三个反引号围栏并标注语言： bash git status git log --oneline 语言标注有助于高亮，但不同渲染器支持的语言不同。选择建议：只在行内代码引用命令、参数、函数名或路径；不要整段文字使用行内代码。代码块与上下文之间留空行，避免被解析为行内内容。

链接、图片与表格

行内链接写法为 `[文字](地址 "标题")`，图片为 ``。替代文字必须描述图片内容，不能只写“图片”。表格使用 GFM 语法，分隔行可控制对齐： | 项目 | 说明 | 状态 | | :--- | :---: | ---: | | A | 示例 | 1 | 单元格内出现竖线需写成 `\|`。表格和任务列表是常见 GFM 扩展，CommonMark 不包含。适用场景：需要展示键值对应或参数说明时使用表格；链接用于引用外部资料；图片仅在文档需要可视化证据时使用。注意：不要用表格做复杂排版。

转义与兼容性

需要显示 Markdown 符号本身时，用反斜杠转义，例如 `\*`、`\_`、`\#`。在代码块或行内代码中不需要转义。判断标准：如果某个符号会被解析为格式标记，而你想显示原字符，就加反斜杠。发布前要确认目标平台对 GFM 扩展的支持情况：GitHub、GitLab 和多数笔记软件支持表格、任务列表和围栏代码；纯邮件或部分论坛可能仅支持基础语法。

发布前检查

完成文档后，按以下顺序检查：

• 标题层级是否从 `##` 开始逐级使用，不跳级。
• 链接是否可打开，图片是否正常显示。
• 代码块语言标注是否正确。
• 表格每行列数是否一致，分隔行对齐是否有效。
• 列表缩进是否错乱，嵌套内容是否属于上一级。
• 是否存在误解析的符号，必要时补转义。

小结：Markdown 适合以文字为主的轻量结构化写作。写作时优先保持纯文本可读性，把标题、列表、代码、链接和表格用最小标记表达清楚；遇到平台扩展如任务列表和表格时，先确认目标环境是否支持。不要用 Markdown 模拟可视化版面，也不要用它生成公文等法定格式。