markdown基本用法

判断 Markdown 用法是否合格，核心标准是：标记最少、层次清楚、渲染稳定、可读性强。先掌握 CommonMark 基础，再按发布平台选择 GFM 扩展，可以避免大部分兼容问题。

一、标题与段落

标题用 `#` 到 `######` 表示，一级标题通常全篇只用一个，正文分节从二级标题开始。不要跳级，例如不要从 `##` 直接到 `####`。写完标题后空一行再写正文，同一节只讨论一个主题。 段落之间用空行分隔，不要用连续空格或 Tab 模拟缩进，否则可能被识别为代码块。普通换行在 CommonMark 中不产生新段落，行尾加两个空格或反斜杠可强制换行；但除非写诗歌、地址，尽量用段落而非强制换行，结构更稳定。

二、强调与行内代码

重点优先用粗体，斜体只用于术语、书名或轻微区分，一页不要过多。写法是 `粗体`、`斜体`、`粗斜体`，星号与文字之间不加空格。中文内容中前后标点可直接衔接，不必额外留空。 命令、路径、参数、文件名等短片段一律用行内代码，如 `config.yaml`、`git status`。行内代码用反引号包裹，避免与引号、括号混淆。如果代码片段中包含反引号，可用双反引号包裹，如 `` `a`b` ``。

三、列表与任务列表

无序列表统一用 `-`，不要混用 `*` 或 `+`；有序列表用 `1.`、`2.`。如果列表项顺序影响结果，用有序列表；没有先后关系则用无序列表。嵌套列表缩进 2 到 4 个空格，同一层级保持一致，前后留空行。 任务列表是 GFM 扩展，写法为 `- [ ] 待办` 和 `- [x] 完成`，适合发布检查、任务清单。并非所有平台都支持任务列表，重要流程应同时保留普通列表或文字说明，避免渲染失败后信息丢失。

四、链接、图片与代码块

链接用 `[文字](url "标题")`，标题可选；图片用 ``。替代文字必须描述图片内容，不能只写“图片”或“截图”，因为图片加载失败时替代文字会被显示。同一文档内路径风格保持一致，仓库内部用相对路径，跨平台发布用完整 URL。 多行代码必须使用三个反引号围栏，并标注语言，例如 ` ```python `。行内代码只用于短片段，长代码放入代码块。如果代码中需要出现反引号，可用更多反引号作为围栏。链接和图片发布前要实际点击检查，确认目标存在且可访问。

五、表格、引用与转义

表格是 GFM 扩展，CommonMark 不原生支持。分隔行用 `| --- | :---: |` 控制左对齐、居中和右对齐，列数必须前后一致，单元格内如需显示管道符要写成 `\|`。纯文本兼容环境优先用列表代替表格；在 GitHub、知识库等支持 GFM 的平台可以使用表格。 引用用 `>`，可嵌套，适合放摘录、提示、风险说明。不要整段使用引用代替正文，否则会弱化层级。需要显示 Markdown 符号本身时用反斜杠转义，如 `\*`、`\_`、`\[`，防止被解析为标记。

小结

Markdown 的目标是减少排版决策，而不是增加修饰。写作时先组织文本结构，再添加最小必要标记。完成后按清单检查：标题层级是否跳级、链接能否打开、图片是否显示、代码块语言是否正确、表格列数是否一致、列表缩进是否统一。