markdown语法大全

Markdown 的价值不在“排版”，而在于用少量符号把结构写进纯文本，保证源码可读、渲染可预期。判断一段 Markdown 是否合格，核心标准只有两条：源码不依赖编辑器，渲染结果与语义一致；目标平台支持所用扩展语法。以下按常用语法分组说明写法、适用场景与注意事项。

标题与段落

标题一律使用井号加空格，`#` 数量对应级别，最多到 `######`。写作时不要跳级：一级标题通常留给文档标题或站点页面，正文分节从 `##` 开始。

• 写法：`## 二级标题`、`### 三级标题`
• 适用场景：文档分节、层级导航、生成目录
• 判断标准：同一级别标题使用同一井号数量；标题后必须有空格
• 注意事项：不建议使用 Setext 下划线标题，它在部分工具中容易与分隔线混淆

段落之间用空行分隔。不要用空格或 Tab 缩进模拟段落，连续多行会被当作同一段落。

强调与引用

强调用于区分重点、术语和提示。粗体优先用于结论和关键词，斜体用于书名、术语或轻微语气，删除线用于变更说明。

• 粗体：`重点`
• 斜体：`术语`
• 删除线：`~~已删除~~`（GFM 扩展）
• 引用：行首 `>`，可嵌套；适合摘录、风险提示、备注

注意事项：同一段内避免粗体、斜体、行内代码混用过密；强调符号紧邻中文或标点时，优先使用 `**` 而非单 `*`，以减少解析歧义。引用块内可以继续使用其他 Markdown 语法。

列表与任务

列表适合步骤、清单、条件罗列。无序列表统一用 `-`，有序列表用 `1.`、`2.`。嵌套列表缩进 2 到 4 个空格，前后留空行更稳妥。

• 写法示例：
• 一级项
• 二级项

任务列表是 GFM 扩展，适合待办、发布前检查：

• [ ] 未完成事项
• [x] 已完成事项

选择建议：顺序影响操作时用有序列表，平行条件或特性用无序列表。不要用列表符号模拟段落，也不要在列表项之间用空行打断同一列表，除非确实需要拆成多个列表。

链接与图片

链接优先使用行内式，简单直接；同一地址重复出现时使用参考式能减少源码噪音。

• 行内链接：`[文字](https://example.com "标题")`
• 图片：``

判断标准：链接文字应能独立说明目标，不要写“点击这里”；图片替代文字必须描述内容，便于屏幕阅读和图片失效时阅读。 注意事项：URL 含空格或括号时要用尖括号包裹，例如 `[文字](<https://example.com/a b>)`。GFM 会自动识别裸链接，但正式文档中仍建议使用显式链接语法。

代码与表格

行内代码用于变量、命令、参数，围栏代码块用于多行代码。围栏代码块必须标注语言，便于高亮和复制。

• 行内代码：`` `npm install` ``
• 代码块：

bash npm install npm run build 行内代码中需要显示反引号时，用双反引号包裹，例如 `` `code` ``。 GFM 表格适合小型对照表，不适合复杂排版。表格分隔行使用 `| --- | :---: |` 控制对齐，单元格内的竖线写成 `\|`。

• 左对齐：`:---`
• 居中对齐：`:---:`
• 右对齐：`---:`

注意事项：表格列数必须每行一致；单元格内容过长时，优先拆分表格或改为列表，而不是在表格中换行。

分隔线与转义

分隔线用于分节，使用三个或以上 `-`、`` 或 `_`，前后留空行。通常使用 `---`，避免与标题下划线歧义。 Markdown 符号需要作为普通字符显示时使用反斜杠转义，例如 `\`、`\_`、`\#`、`\[`。需要显示反斜杠本身则写 `\\`。 兼容性提醒：脚注、任务列表、自动链接、删除线是 GFM 或常见扩展，不是 CommonMark 标准。跨平台发布前应确认目标平台支持，否则优先使用基础语法。

小结

写作时先确定文档层级，再按“标题—段落—列表—代码/表格—链接”的顺序组装内容。优先使用基础语法，确实需要任务列表、删除线、表格等扩展时，确认目标平台支持。完成后检查：标题是否跳级、列表缩进是否一致、链接是否能打开、代码块语言是否正确、表格列数是否对齐。只要源码可读、渲染结果与语义一致，就是可发布的 Markdown。