Markdown文档

要判断一份 Markdown 文档是否合格，核心标准是：结构可扫读、语法可渲染、维护成本低。满足这三条，通常就能作为可靠的技术文档、项目说明或知识库内容长期使用。

适用场景与边界

Markdown 最适合以标题、列表、代码块、表格和链接为主的文本内容，例如 README、接口说明、操作手册、个人笔记和静态站点源文件。判断标准：如果内容主要靠文字结构和少量标记表达，选择 Markdown 成本最低；如果需要精确分页、多栏排版、复杂字体控制或公文格式，不应使用 Markdown，而应切换到排版工具或模板。

基础语法与渲染差异

日常写作只需掌握少量语法：

• 标题：`#` 至 `######`，一个文档通常只保留一个一级标题，二级标题作为主要分节，不跳级。
• 列表：无序列表用 `-`，有序列表用 `1.`、`2.`；嵌套列表缩进 2 到 4 个空格。
• 强调：重点用粗体 `重点`，斜体 `术语` 只用于书名或轻微区分。
• 引用：`>` 适合放置提示、风险说明，可嵌套使用。
• 代码：行内代码用反引号，代码块用三个反引号并标注语言，例如 ` ```python `。

渲染差异方面，CommonMark 是基础标准，GitHub Flavored Markdown（GFM）额外支持表格、任务列表和删除线。发布到不同平台前，先确认目标平台是否支持 GFM 扩展，避免表格或任务列表失效。

结构设计与可扫读性

写作前先列标题大纲，再填充段落，能显著减少返工。每节只讲一个主题，开头用一句话说明本节结论，避免长段落。可执行步骤：

1. 列出二级标题，形成文档骨架；
2. 为每个标题写一句核心结论；
3. 补充必要列表、示例或注意事项；
4. 将超过 300 字的段落拆分为短段或列表。

注意：标题层级不能跳级，例如 `##` 后面直接使用 `####` 会破坏大纲结构，也不利于渲染和阅读。

表格、链接与图片

表格使用 GFM 语法，分隔行可控制对齐： | 项目 | 说明 | 优先级 | | :--- | :---: | ---: | | 语法 | 列数必须一致 | 高 | 链接使用行内格式 `[文字](地址 "标题")`，图片使用 ``。替代文字应准确描述图片内容，既是无障碍要求，也能在图片加载失败时提供上下文。 注意事项：单元格内出现 `|` 必须写成 `\|`；插入图片前确认地址可访问，不要在文档中引用本地临时路径。

协作与发布前检查

在团队协作中，Markdown 文件建议使用 UTF-8 编码、统一换行风格，并纳入 Git 管理。提交前至少做一次本地渲染预览，编辑器如 VS Code 或 Typora 自带预览功能，能发现大部分语法错误。 发布前逐项检查：

• 标题层级是否跳级；
• 链接能否打开；
• 图片是否正常显示；
• 代码块语言标注是否正确；
• 表格列数是否一致；
• 列表缩进是否错乱；
• 需要显示 Markdown 符号本身时是否已用反斜杠转义。

小结

Markdown 的优势并非排版能力，而是用少量标记换取可读、可维护、可版本化的文本。只要控制好适用边界、遵循语法规范，并在发布前完成渲染检查，它就能承担大多数技术文档和知识整理工作。