markdown语法

Markdown 语法的核心判断标准是：一篇文档是否可读、可维护、可迁移，取决于是否只用少量基础符号表达结构，而不是依赖某个编辑器的按钮或私有扩展。建议优先掌握 CommonMark 基础语法，再按需使用 GFM 扩展。

标题与段落

标题用 `#` 到 `######`。通常一个文档只保留一个一级标题，即文档主标题；分节用二级标题 `##` 开始，不要从 `#` 直接跳到 `###`。标题文字前加一个空格。 段落之间用空行分隔，不要用多个空行。如果确实需要手动换行，在行尾加两个空格或使用反斜杠 `\`；大多数情况下让编辑器自动折行即可。

• 适用场景：README、技术文档、笔记的分节。
• 常见错误：段落开头输入四个空格会被渲染为代码块；连续空行不会增加间距，反而影响可读性。
• 判断标准：打开源文件时，应能一眼看出层级；如果需要在预览和源码间反复对照，说明标题或空行使用不一致。

强调与引用

粗体 `文字` 适合操作名、结果、关键限制；斜体 `文字` 适合术语、书名、新引入的概念。粗斜体 `文字` 很少需要，一屏出现一次以上通常说明重点过多。引用 `>` 适合放注意、风险、外部摘录；可多级嵌套，但普通技术文档使用一级就够。 > 注意：删除文件前先确认路径，避免误删。

• 适用场景：突出错误提示、命令输出、版本差异。
• 注意事项：不要整段使用粗体或斜体，也不要在同一句里强调多个词；重点应集中。

列表与任务

无序列表统一用 `-`，不要混用 `*` 和 `+`。有序列表用数字加点，渲染结果通常会自动递增，但源码中最好按顺序写，便于阅读。嵌套列表缩进 2 到 4 个空格，过多缩进会让层级混乱。 任务列表是 GFM 扩展：

• [ ] 待补充示例
• [x] 已验证链接
• 适用场景：操作步骤、功能清单、待办事项。
• 注意事项：任务列表在部分平台不显示复选框；如果目标是纯 CommonMark 环境，应改用普通列表。

代码与链接

行内代码用反引号，例如 `git status`；若代码中本身包含反引号，可用双反引号包裹。代码块用三个反引号并标注语言，语言名放在第一组反引号后。语言标注要准确，否则换行和高亮可能错误。 bash git status 链接写作 `[文字](地址 "标题")`。链接文字应说明去向，例如“查看 API 文档”而非“点击这里”。地址需要可访问，相对路径和绝对路径要区分。

• 适用场景：命令、配置项、函数名、外部参考资料。
• 常见错误：代码块开始和结束的反引号数量必须一致；链接中的引号要成对。

表格与图片

表格用竖线和连字符： | 功能 | 语法 | | --- | :---: | | 粗体 | `文字` | 分隔行用 `---` 或 `:---:` 控制对齐。列数必须一致，单元格内出现 `|` 时写成 `\|`。表格适合参数对比、字段说明，不适合承载长段落。 图片写作 ``。替代文字应描述图片内容，例如“登录页面截图”，而不是“图片”；当图片无法加载时，替代文字是唯一信息。

• 适用场景：参数表、状态对照、界面截图。
• 注意事项：发布前逐行检查表格列数；图片地址失效时要有替代说明。

转义与扩展语法

要显示 Markdown 符号本身，在符号前加反斜杠，例如 `\*`、`\_`。自动链接可用尖括号 `<https://example.com>`。删除线 `~~文字~~`、任务列表、表格属于 GFM 扩展，不是所有 CommonMark 环境都支持。

• 选择建议：跨平台、多编辑器协作时，优先使用 CommonMark 基础语法；只在确认支持 GFM 的环境中用扩展。
• 发布前检查：标题是否跳级、链接是否可达、表格列数是否一致、列表缩进是否错乱、代码块语言是否标注。

小结

先定结构，再填内容。写完源文件后按“标题、链接、表格、代码块、列表”顺序检查，能减少渲染差异。不要为了视觉效果依赖平台私有语法；基础语法已经能覆盖绝大多数文档需求。