markdown语法总结

Markdown 的价值在于把“内容结构”写成纯文本，同时能被稳定渲染。判断一份 Markdown 是否合格，看三点：源文件不渲染也能读；标题、列表、代码块层级清楚；在目标平台（GitHub、Typora、语雀、博客系统等）预览无错位。学习顺序建议先掌握 CommonMark 核心语法，再按平台补充表格、任务列表、脚注等扩展。

标题与段落：先建立结构

标题用 `#` 到 `######`，分别对应一级到六级。一个文档通常只用一个一级标题，二级标题作为主要分节，避免从一级直接跳到三级。写法：`## 小节名`，`#` 后加一个空格。 段落之间用空行分隔。若要在段内强制换行，可在行尾输入两个空格再回车；但更推荐拆成新段落。不要用连续空格或 Tab 模拟缩进，否则可能被识别为代码块。写作时先列标题大纲，再填段落，能显著减少返工。

强调、列表与引用：提高可扫读性

强调用 `斜体` 或 `_斜体_`，`粗体`，`粗斜体`。中文排版中，斜体可读性一般，建议只用于术语、书名或需要轻微区分的词；重点优先用粗体，但一页不要过多。 无序列表用 `-`、`*`、`+`，建议统一用 `-`。有序列表用 `1.`、`2.`，实际数字不影响渲染，但源文件最好顺序正确。嵌套列表缩进 2 到 4 个空格，前后留空行更稳。项目符号后要有一个空格。 引用用 `>`，可嵌套为 `>>`，内部可以放列表、代码等。适合放摘录、提示、风险说明。若引用很长，可每行都加 `>`，或只在首行加。

链接、图片与分隔线：路径与可访问性

行内链接：`[显示文字](https://example.com "标题")`。自动链接可写 `<https://example.com>`。同一链接多次出现时，用引用式链接 `[文字][id]`，并在文末写 `[id]: https://example.com`。 图片：``。替代文字要能描述图片内容，不要写“图片”。本地图片建议用相对路径，例如 `./images/a.png`，便于仓库迁移。分隔线用单独一行的 `---` 或 `***`，前后留空行；紧跟文字时，`---` 可能被解析为二级标题的下划线。

代码、表格与任务列表：技术文档常用

行内代码用反引号，如 `` `npm install` ``。代码块用三个反引号包裹，并标注语言： js const a = 1; 不标语言也能显示，但高亮和可读性会下降。缩进四空格也可形成代码块，但不推荐，容易和列表嵌套冲突。 表格是 GFM 扩展：表头 `| 列 A | 列 B |`，分隔行 `| --- | :---: |`，冒号控制对齐。单元格内的 `|` 要写成 `\|`。任务列表写 `- [ ] 待办`、`- [x] 完成`，适合 README 和 issue 模板，但并非所有平台都支持。

转义、兼容与发布检查：避免渲染翻车

需要显示 Markdown 符号本身时，用反斜杠转义：`\*`、`\_`、`\#`、`\[`、`\]`、`` \` ``、`\|` 等。直接内嵌 HTML 可能被平台过滤，尤其是脚本和样式，不要作为主要排版手段。 不同平台差异集中在换行规则、表格、脚注、删除线、任务列表、目录和公式。核心语法用 CommonMark；GitHub、GitLab 等通常兼容 GFM。发布前检查：标题层级是否跳级、链接能否打开、图片是否显示、代码块语言是否正确、表格列数是否一致、列表缩进是否错乱。 小结：把 Markdown 当作结构化文本，而不是可视化排版工具。优先掌握标题、段落、列表、链接、代码和引用；表格、任务列表、脚注按平台选用。每次发布前在目标环境预览一次，能解决大多数兼容问题。