Markdown 语法

判断 Markdown 写作是否合格，优先看它在不渲染时是否仍然层次清楚、重点明确。渲染不是补救手段，纯文本可读性本身就是语法的一部分。Markdown 最适合技术文档、说明、笔记、评论和静态页面正文，不适合需要精确分页、复杂图文混排或法定公文格式的场景。写作时遵守两条底线：不要用连续空格或 Tab 模拟缩进；段落之间用空行分隔，不要依赖单次换行。以下按常用元素给出判断标准与写法建议。

一、标题与段落

标题用 `#` 到 `######` 表示，井号后必须留一个空格。一级标题通常一个文档只保留一个，用于文档标题；正文分节从 `##` 开始，不要跳级，例如不要从 `##` 直接跳到 `####`。判断标准是：去掉渲染后，标题与正文的层级是否一眼可辨。 段落写作中，一句或一组紧密相关的句子构成一段，段间空行。不要在段落内用多个空格制造缩进，也不要用空行把同一主题切得过碎。如果段落内出现长串说明，优先拆成项目列表，减少扫读成本。 示例：

二、标题与段落

标题用 `#` 到 `######` 表示，井号后必须留一个空格。

二、强调、引用与转义

强调分为粗体和斜体。粗体用 `文本`，适合标出关键结论、操作结果或需要立即注意的词；斜体用 `文本`，适合术语、书名或轻微区分。一屏内不要大量使用强调，否则会失去重点。判断标准是：如果一段里一半文字都被加粗，就等于没有强调。 引用用 `>`，可以嵌套，适合放摘录、提示、风险说明或补充条件。引用内容不要大段复制，应截取与当前主题直接相关的一两句。 需要显示 Markdown 符号本身时，用反斜杠转义，例如 `\#`、`\*`、`\[`。在表格单元格中显示 `|` 时写作 `\|`。不确定是否会被渲染时，优先放在代码块或行内代码中。

三、列表与任务列表

普通列表使用 `-` 作为无序列表符号，不使用 `*` 或 `+`，保持文档统一。有序列表使用 `1.`、`2.`，不要手动维护复杂编号，Markdown 渲染器会自动递增。嵌套列表缩进 2 到 4 个空格，前后留空行，避免与段落粘连。 任务列表是 GFM 扩展语法，写作：

• [ ] 待处理项
• [x] 已完成项

使用任务列表前，确认目标平台支持 GFM。很多编辑器和静态站点支持，但纯 CommonMark 环境不支持。如果文档可能被迁移，建议将任务列表作为进度展示，不作为唯一的信息记录方式。

四、代码、链接与图片

行内代码用单个反引号包裹，适合标注命令、参数、文件名或字段名。代码块用三个反引号并标注语言，例如： `markdown python print("hello") ` 语言标注可以帮助编辑器做语法高亮，但不要随意标注不存在的语言。行内代码不要与代码块混用：行内代码用于短语，代码块用于完整片段或需要保留缩进的示例。 链接使用 `[文字](地址 "标题")`，标题可省略。链接文字应说明目标内容，不要用“点击这里”。图片使用 ``，替代文字必须描述图片内容，不能为空，否则无法通过可访问性检查。发布前必须打开链接、确认图片地址可访问。

五、表格与注意事项

表格适合展示对比、参数、字段说明等结构化内容。GFM 支持表格，CommonMark 不直接支持，使用前确认发布环境。表格写法： | 元素 | 写法 | 说明 | | --- | --- | --- | | 粗体 | `文本` | 用于关键结论 | | 行内代码 | 单个反引号包裹 | 标注命令或字段 | 分隔行的 `---` 决定列数，左右加冒号可以控制对齐，例如 `:---` 左对齐、`:---:` 居中。表格列数必须一致，单元格内出现竖线时写成 `\|`。不要用表格实现复杂布局或嵌套段落。

结尾小结

写 Markdown 时，先确认目标平台支持 CommonMark 还是 GFM，再决定是否使用任务列表和表格。发布前按清单检查：标题层级是否跳级、段落是否用空行分隔、列表缩进是否统一、代码块语言是否标注、链接是否可打开、图片替代文字是否填写、表格列数是否一致。满足这些条件，纯文本可读性通常不会差。