markdown 语言

判断 Markdown 是否适合当前文档，可以看三个条件：内容是否以文本为主、是否需要长期可读、是否会被多人编辑或版本管理。只要满足其中两项，使用 Markdown 通常比二进制格式和排版工具更稳。Markdown 的价值不在视觉装饰，而在结构稳定、可转换、可 diff。

一、先确定方言：CommonMark 还是 GFM

写作前先明确渲染环境。GitHub、GitLab、多数代码托管平台和 VSCode 预览使用 GFM；部分静态站点生成器或严谨文档工具以 CommonMark 为基准。选择方法是：需要表格、任务列表、删除线时选 GFM；追求最大兼容性时只写 CommonMark 子集。如果无法确认目标环境，只使用标题、段落、列表、链接、图片、代码块、引用这七类语法。脚注、数学公式、自动链接属于平台扩展，不应成为关键信息的唯一载体。

二、只使用必要的基础语法

一个文档通常只保留一个一级标题，分节用二级标题，不要从一级直接跳到三级。列表用 `-` 表示无序，用 `1.` 表示有序；嵌套列表缩进两到四个空格，并在前后留空行。强调优先使用粗体，斜体只用于术语或书名。可执行步骤：写完大纲后逐项检查标题层级，确认没有跳级；若发现列表紧邻无缩进文本导致解析中断，应补空行或调整缩进。不要用连续空格或 Tab 模拟排版缩进，渲染结果不可控。

三、表格与任务列表按 GFM 使用

表格适合字段少、每格内容短的结构化信息。写法是：表头一行、分隔行一行、数据行若干；分隔行用 `| --- | :---: |` 区分左对齐、右对齐和居中。单元格内出现 `|` 时要写成 `\|`。完成后必须逐行数清列数，列数不一致会导致表格错乱。任务列表写作 `- [ ] 待办`、`- [x] 完成`，但它并非所有平台都支持，正式文档不应把任务状态只记录在任务列表里。超过三列或单元格较长时，建议改用定义列表或小标题加段落。

四、代码块与转义避免解析事故

行内代码用单个反引号包裹，如 `git status`；多行代码用三个反引号并标注语言： python def add(a, b): return a + b 语言标注应写为 `python`、`bash`、`json` 等，不要留空，否则高亮和可读性都会下降。需要显示 Markdown 符号本身时用反斜杠转义，例如 `\*` 显示为星号。注意反引号内部不要出现同级反引号；代码块内容若包含三个反引号，可改用更多反引号作为围栏。图片必须写有实际意义的替代文字，例如 ``，只写“图片”或空替代文字会影响可访问性。

五、发布前检查清单

• [ ] 标题层级是否逐级展开，无跳级。
• [ ] 链接能否打开，站内锚点是否有效。
• [ ] 图片是否可加载，替代文字是否描述内容。
• [ ] 表格每行列数是否一致，分隔行是否存在。
• [ ] 列表缩进是否统一，嵌套是否前后留空行。
• [ ] 代码块语言标注是否正确，转义是否到位。
• [ ] 是否在目标平台预览一次，或用 `markdownlint` 检查。

Markdown 的可靠性来自语法克制。选择一种明确方言，控制扩展语法范围，并在发布前按清单检查，比追求花哨渲染更能保证文档长期可维护。能不用扩展就不用扩展；需要扩展时，确保读者和目标平台都能解析。