Markdown Cheat Sheet 完整指南:常用语法、表格、任务列表、代码块与兼容性检查

Q: 标题后为什么必须留空格?

空格能明确区分 ATX 标题与普通文本,并提升不同解析器之间的一致性。推荐写成 ## 标题 。

Markdown Cheat Sheet 快速答案

先记结构,再记装饰。

日常写作优先掌握标题、段落、列表、链接、图片、引用和代码;表格、任务列表、删除线等功能属于常见扩展,发布前必须在目标平台实际预览。Markdown 的价值不是语法更花哨,而是让内容源文件保持清晰、可比较、可复用和便于转换。

这份速查表不仅给出可复制语法,还解释何时使用、哪些写法容易失效,以及怎样验证 GitHub、编辑器、文档站和转换工具中的最终结果。示例中的网址和文件名均为占位内容,使用时请替换成真实、可访问的目标。

最常用的 Markdown 基础语法

目的	Markdown 写法	使用说明
一级标题	`# 页面标题`	一篇文档通常只保留一个一级标题。
二级标题	`## 章节标题`	用于组织主要章节,不要跳级。
粗体	`重点内容`	强调结论,不要整段加粗。
斜体	`术语或轻度强调`	避免与星号列表混写造成歧义。
链接	`[描述性文字](https://example.com)`	锚文本应说明目标,不写"点击这里"。
图片	`![图片说明](images/example.png)`	替代文本应说明图片的信息作用。
行内代码	`npm run build`	适合命令、变量、文件名与短代码。

标题井号后应留一个空格,段落之间保留空行。很多"Markdown 没生效"的问题并非语法本身错误,而是缺少空格、代码围栏未闭合,或列表前后没有留出稳定的块级边界。

列表、任务列表和引用怎么写

无序列表

使用 - 项目,嵌套层级统一缩进。不要在同一列表中随意混用星号、加号和短横线。

有序列表

使用 1. 步骤。源文件可连续写 1,但需要精确审阅顺序时,建议保留真实编号。

任务列表

在支持 GFM 的平台使用 - [ ] 待办 与 - [x] 完成;普通 CommonMark 渲染器可能只显示文本。

引用

使用 > 引用内容。引用必须标明来源,不能把普通提示框误写成第三方引文。

复杂列表最容易在换行后断裂。列表项内若包含多个段落、代码块或图片,应保持一致缩进,并在目标渲染器中检查编号是否重置、代码是否仍属于当前条目。

代码块、反引号与特殊字符转义

多行代码使用三个反引号围栏,并在起始围栏后标注语言,例如 ```sql。结束围栏必须单独成行。代码本身含有三个反引号时,可以改用更长的围栏,避免解析器提前关闭代码块。

```sql
SELECT customer_id, COUNT(*) AS orders
FROM orders
GROUP BY customer_id;
```

需要原样显示 *、_、#、[ 等 Markdown 控制字符时,可在前面加反斜杠。是否必须转义取决于字符所在位置;不要为了"保险"给所有标点都加反斜杠,否则源文件会变得难读。

Markdown 表格、对齐与单元格限制

常见表格由表头、分隔行和数据行组成。分隔行中的冒号控制对齐::--- 左对齐、:---: 居中、---: 右对齐。每行列数应一致,单元格中的管道符需要写成 \| 或改用代码形式。

| 指标 | 当前值 | 状态 |
| :--- | ---: | :---: |
| 覆盖率 | 92% | 通过 |
| 错误数 | 3 | 复核 |

表格不是 CommonMark 核心语法,而是 GitHub Flavored Markdown 等实现的扩展。内容包含长段落、复杂列表、合并单元格或多行结构时,不要强行使用 Markdown 表格,应改成列表、卡片或原生 HTML 表格。

链接、图片、相对路径和锚点检查

1确定发布位置。
相对路径会随当前文件位置解析;移动文档前先检查图片目录和被引用文件。
2使用描述性锚文本。
让读者在不读取上下文时也知道链接通向规范、工具还是示例。
3验证标题锚点。
不同平台对大小写、标点、空格、中文字符和重复标题的处理可能不同。
4检查图片交付。
确认文件随文档一起提交、大小合适、替代文本准确,且目标环境不会阻止远程图片。

CommonMark、GFM 与平台扩展如何选择

需求	优先方案	风险
跨平台基础文档	CommonMark 核心语法	功能较少,但兼容范围更清晰。
GitHub README 与 Issue	GFM 表格、任务列表、删除线	迁移到其他平台可能退化。
文档站点	项目规定的 Markdown 方言	自定义容器、组件和 front matter 依赖构建器。
Word/PDF 交付	先用标准语法,再做格式转换	分页、字体、表格宽度和代码换行需要二次检查。

不要假设"能在编辑器预览"就代表所有平台都能正确显示。项目应明确 Markdown 方言、渲染器版本、允许的 HTML 范围以及发布前的真实预览环境。

建议建立一份最小兼容性样例，至少包含连续标题、嵌套列表、任务列表、宽表格、围栏代码、多语言文字、相对图片、带括号的链接和脚注占位。分别在源代码仓库、文档站点、目标编辑器以及最终转换工具中渲染同一份样例，并记录每个平台支持、降级或拒绝的语法。若内容需要长期维护，应优先保留 CommonMark 核心结构，把平台专有容器、自动目录、数学公式和嵌入组件隔离在有明确负责人和回退方案的扩展层。这样可以在迁移渲染器或输出 Word、PDF 时快速发现差异，而不是等到正式文档发布后逐页修复。

从 Markdown 草稿到可靠交付的工作流

1先写语义结构。
用一个 H1 和连续的 H2 组织问题、步骤、证据与结论,再补充强调和视觉元素。
2运行语法检查。
检查未闭合围栏、断裂链接、重复标题、混乱缩进、尾随空格和不一致列表。
3在目标平台预览。
重点查看目录锚点、表格宽度、代码换行、图片路径和任务列表。
4转换并复核。
输出 Word 或 PDF 后检查分页、标题层级、可复制文本、超链接、图片清晰度和文件名。
5保留源文件。
将 Markdown、图片和配置纳入版本管理,记录渲染器或转换参数,便于复现。

常见 Markdown 错误及修复方法

标题只加粗不使用井号:视觉像标题,但无法形成正确目录和语义结构。
链接文字与目标不符:更新 URL 时同时复核锚文本和上下文。
代码围栏遗漏结束符:会让后续整篇内容变成代码,应由 lint 或预览及时发现。
表格列数不一致:补齐空单元格,或将过长信息拆为列表。
使用本机绝对路径:换设备后图片失效,应使用项目内相对路径。
依赖不可移植扩展:发布前明确目标渲染器,必要时提供兼容降级。

发布前 Markdown 检查清单

结构:只有一个主标题,层级连续,段落与列表边界清楚。

内容:术语一致,示例可执行,引用有来源,没有敏感数据或虚构结论。

资源:图片路径有效、替代文本准确、链接无 404、锚点可跳转。

呈现:桌面与手机预览正常,表格可读,代码不溢出,转换文件经过二次检查。

使用 InfiniSynapse 完成文档转换

完成格式、隐私和兼容性检查后,可以使用 InfiniSynapse 文档工具处理已脱敏内容。下载结果后,请继续在目标应用和实际交付环境中检查标题、表格、图片、链接、分页与文件类型。

打开 Markdown 转 Word 工具进入 InfiniSynapse

Markdown Cheat Sheet 常见问题

Markdown 是否在所有平台显示一致?

不一定。核心语法通常相近,但表格、任务列表、删除线、数学公式、脚注和 HTML 支持取决于具体方言与渲染器。

标题后为什么必须留空格?

空格能明确区分 ATX 标题与普通文本,并提升不同解析器之间的一致性。推荐写成 ## 标题。

Markdown 可以直接作为最终交付文件吗?

可以用于开发和知识库场景;面向客户或打印时,通常还需要转换为 Word 或 PDF,并检查分页、字体、表格和链接。

如何避免 Markdown 链接和图片在迁移后失效?

使用稳定的项目相对路径,保持资源目录随文档移动,并在目标仓库或站点的真实路径下运行链接检查。

Markdown 语法与兼容性权威来源

关于本指南

InfiniSynapse 编辑团队

本指南面向需要编写、审查、转换和交付 Markdown 文档的个人与团队。示例用于解释语法和验证方法,不代表特定平台的性能承诺。