Markdown教程

判断 Markdown 是否适合当前任务，主要看两点：内容是否以文字为主，以及是否需要长期维护、版本管理或多平台发布。如果答案都是“是”，Markdown 通常比二进制文档更可靠。它不擅长复杂分页、精确版式和多栏排版，这类需求应选择排版工具或办公套件。

适用场景与工具选择

适用场景包括：仓库说明文档、技术笔记、博客草稿、论坛回复、内部知识库、API 文档等。判断标准建议：内容需要频繁修改、多人协作或跨平台转换时，优先使用 Markdown；一次性打印或严格公文排版则不适合。 工具可按用途分类：

• 编辑器：VS Code、Typora、Obsidian、Zettlr，适合日常写作。
• 转换器：Pandoc 可将 Markdown 转为 HTML、DOCX、PDF 等。
• 预览：编辑器内置预览足够，发布前再用目标平台渲染一次。

注意各平台方言差异。GitHub、Notion、飞书等支持不同扩展，迁移时应先确认渲染效果。

基础语法：标题、段落与强调

标题用 `#`，一级标题对应 `#`，二级对应 `##`，最多到六级。推荐从二级开始组织正文，一级通常用于文档标题或文件标题；不要跳级使用，例如二级后直接出现四级，会破坏层级和可读性。 段落之间必须空一行。连续书写但想换行时，可在行尾添加两个空格或使用反斜杠 `\`，但为了减少兼容问题，建议直接另起段落。 强调优先用 `粗体` 表示重点，`斜体` 用于术语、书名或轻微区分。行内代码用反引号，例如 `printf()`。注意不要整段使用粗体或斜体，否则会失去强调效果。

列表、引用与代码

无序列表用 `-`，有序列表用 `1.`、`2.`。列表前后建议空行，嵌套列表缩进 2 到 4 个空格：

• 一级项
• 二级项
• 二级项
• 一级项

如果嵌套缩进不一致，部分渲染器会将其解析为独立列表。 引用用 `>`，适合写提示、摘录或风险说明： > 注意：不要用 Markdown 生成法定公文格式，应使用公文模板或专用排版工具。 代码块用三个反引号包裹，并标注语言： python def add(a, b): return a + b 不标注语言时，代码块只按普通文本渲染，可能缺少高亮。行内代码用于变量、命令或路径，如 `config.yaml`。

链接、图片与表格

行内链接格式为 `[文字](地址 "标题")`，例如 `[CommonMark](https://commonmark.org "CommonMark 规范")`。链接文字应说明目标内容，不要写“点击这里”。 图片格式为 ``。替代文字必须描述图片内容，便于无法加载或使用屏幕阅读器时理解。不要省略替代文字，也不要用“图片”这样的无意义描述。 表格使用 GFM 语法，分隔行通过 `| --- | :---: |` 控制对齐： | 功能 | 写法 | 说明 | | :--- | :--- | :--- | | 粗体 | `文字` | 重点强调 | | 删除线 | `~~文字~~` | GFM 扩展 | 单元格内出现竖线时需转义为 `\|`，列数必须保持一致，否则表格无法正常渲染。复杂表格建议拆成多个简单表格，避免在移动端阅读困难。

常见扩展与平台差异

CommonMark 是基础规范，GFM 在 CommonMark 之上增加了表格、任务列表、删除线、自动链接等扩展。不同平台支持程度不同：

• 任务列表：`- [ ] 待办`、`- [x] 完成`，GitHub、GitLab 等支持，部分静态站点不支持。
• 删除线：`~~已删除~~`，GFM 支持，CommonMark 无此语法。
• 自动链接：`https://example.com` 在 GFM 中自动可点击，CommonMark 需要尖括号 `<https://example.com>`。

写作时优先使用 CommonMark 语法子集；确需扩展特性时，先确认目标平台支持。不要在同一文档混用不同平台的私有语法。

写作规范与导出检查

发布前按清单检查：

• 标题层级是否连续，无跳级。
• 所有链接是否可打开，锚点是否有效。
• 图片地址是否正确，替代文字是否清晰。
• 代码块是否标注语言，缩进是否统一。
• 表格每行列数是否一致，分隔行是否正确。
• 列表前后是否有空行，嵌套是否对齐。

使用 Pandoc 导出 HTML 或 PDF 时，可指定 CSS 或模板控制版式，但不要期望 Markdown 实现像素级排版。PDF 导出建议先转为 HTML 再打印，或使用 Pandoc 配合 LaTeX。 最后，从最小可用语法集开始：标题、段落、粗体、列表、链接、代码块。大多数文档用这几种即可完成。保持源码可读，比依赖扩展语法更重要。定期用目标平台渲染一次，比事后修复兼容问题成本低得多。