markdown 语法大全

判断 Markdown 语法是否“能用”，先确认目标平台遵循 CommonMark 还是 GitHub Flavored Markdown（GFM）。日常写作优先掌握五类语法：块级结构、行内强调、列表与任务、链接图片、代码表格。其余扩展语法只应在平台支持时使用，否则宁可改写为普通段落或表格。

一、块级语法：先搭骨架，再填内容

块级语法决定文章结构和可扫读性。最常用的是标题、段落、引用、分隔线。标题用 `#` 至 `######`，通常一个文档只保留一个一级标题；正文小标题从 `##` 开始，不跳级。段落之间必须空行，不要用连续空格或 Tab 模拟缩进。引用用 `>`，适合放置提示、风险说明或摘录；分隔线用 `---`，前后留空行。 适用场景：文档大纲、长文分节、说明性段落。判断标准：每个二级标题只讲一个主题；标题层级同级并列，不出现 `##` 后直接接 `####`。步骤：先列出标题大纲，确认层级关系，再逐段填充。注意：块级符号后通常留一个空格，例如 `## 标题`。

二、行内语法：只强调真正重要的词

行内语法包括粗体 `重点`、斜体 `术语`、行内代码 `code`、删除线 `~~删除~~`。粗体适合标记操作对象、必选项或结论；斜体只用于术语、书名或轻微区分；行内代码用于文件名、命令、参数、函数名。 适用场景：突出关键信息、标识技术术语。判断标准：一屏内粗体不超过 3～5 处，否则重点会被稀释；同一句话不要既加粗又斜体。步骤：先确定读者必须看到的词，再决定是否加粗；技术写作优先使用行内代码而不是引号。注意事项：如果文字本身需要显示星号、下划线或反引号，用反斜杠转义，如 `\*`；不要整句加粗。

三、列表与任务：步骤用有序，选项用无序

列表用于拆解步骤、条件和检查项。无序列表统一用 `-`，有序列表用 `1.`、`2.`；嵌套列表缩进 2 到 4 个空格，前后留空行。任务列表用 `- [ ]` 表示待办，`- [x]` 表示完成。 适用场景：操作步骤、功能清单、发布前检查、需求拆解。判断标准：必须按顺序执行的内容用有序列表；并列选项、注意事项用无序列表；需要标记完成状态时再用任务列表。步骤：先写出条目，再判断是否需要顺序；若条目超过 7 项，考虑分组或拆成多个小标题。注意事项：任务列表不是所有平台都支持，发布前应确认目标环境；不要用列表项模拟段落，较长的说明应写成自然段。

四、链接与图片：可读的替代文字，可验证的地址

链接用行内式 `[文字](url "标题")`，图片用 ``。链接文字应能独立表达目标内容，避免只写“点击这里”；图片替代文字要能描述图片内容，供屏幕阅读器和加载失败时使用。 适用场景：引用资料、跳转至相关章节、插入截图或示意图。判断标准：删除链接文字后，句子仍能读懂；图片缺失时，替代文字能传达必要信息。步骤：先写正文，再为关键名词添加链接；图片先确定替代文字，再补地址和标题。注意事项：标题属性通常显示为悬停提示，不是所有场景都需要；URL 中包含空格、括号等特殊字符时应使用百分号编码；发布前逐一点击链接，确认地址有效。

五、代码与表格：结构化数据的唯一来源

行内代码用单个反引号包裹，代码块用三个反引号并标注语言，例如 ` ```python`。表格使用 GFM 格式，分隔行用 `| --- | :---: |` 控制对齐；单元格内需要显示竖线时写成 `\|`。 适用场景：命令示例、配置片段、参数对比、版本差异。判断标准：代码块必须标注语言，否则高亮和可读性都会下降；表格每一行列数必须一致。步骤：代码块前用一句话说明这段代码解决什么问题；表格先确定列名和数据对齐方式，再逐行填充。注意事项：CommonMark 不包含表格语法，GFM 扩展支持；若目标平台不支持表格，改用列表或段落描述。不要用制表符对齐表格。

小结

Markdown 的价值在于源文本可读、可维护，而不是实现复杂排版。写作时按“结构 → 重点 → 数据”的顺序使用语法：先用块级语法搭骨架，再用行内语法标重点，最后用列表、代码和表格承载步骤与数据。发布前检查五项：标题层级是否跳级、链接能否打开、图片是否显示、代码块语言是否正确、表格列数是否一致。扩展语法如脚注、任务列表、数学公式，只在确认目标平台支持时使用；否则优先改写成普通段落、列表或代码块。