Markdown 写作完全指南：2026 年最佳实践与高级技巧

Markdown 诞生于 2004 年，John Gruber 的初衷很简单：让纯文本文件在不渲染的情况下也具备良好的可读性。二十年过去，Markdown 已成为技术写作的事实标准，从 GitHub README 到技术博客，从 API 文档到知识库，无处不在。

但很多人只会用几个基本语法，遇到复杂场景就手足无措。这篇指南将从历史脉络讲到实战技巧，帮你真正掌握 Markdown。

Markdown 的主流变体

Markdown 规范并不统一，这是它最大的"历史遗留问题"。

CommonMark：2014 年由 Jeff Atwood 等人发起，目标是建立一套无歧义的 Markdown 规范。现在大多数渲染引擎（包括 GitHub、GitLab）都以 CommonMark 为基础。

GFM（GitHub Flavored Markdown）：GitHub 在 CommonMark 基础上扩展的变体，增加了表格、任务列表、删除线、自动链接等特性。是目前使用最广泛的 Markdown 变体。

MultiMarkdown：扩展了脚注、表格、引用等功能，主要在学术写作圈流行。

MDX：在 Markdown 中嵌入 JSX 组件，专为 React 技术栈设计，是现代文档站点（如 Docusaurus、Nextra）的首选。

实际写作时，优先以 GFM 为准——它的兼容性最广，绝大多数平台都支持。

基础语法速查

标题

# 一级标题（每篇文章只用一次，通常作为文章标题）
## 二级标题（主要章节）
### 三级标题（子章节）
#### 四级标题（尽量避免，层级太深影响可读性）

核心原则：一篇文档只有一个 h1。如果你在博客发布，文章标题通常由平台自动生成 h1，正文就从 ## 开始写。

文本格式

**粗体文本** 或 __粗体文本__
*斜体文本* 或 _斜体文本_
~~删除线文本~~（GFM 支持）
`行内代码`
> 引用块，适合摘录或注意事项

列表

- 无序列表项（推荐用 - 而不是 * 或 +，统一风格）
  - 缩进两个空格表示子项
  - 子项二

1. 有序列表项
2. 第二项
3. 第三项（序号可以全写 1.，渲染时自动排序）

链接与图片

[链接文字](https://example.com "可选标题")
![图片 alt 文字](https://example.com/image.png "可选标题")

<!-- 引用式链接，适合长文中重复引用同一链接 -->
[链接文字][ref-id]
[ref-id]: https://example.com

进阶语法

代码围栏：始终指定语言

代码块的正确写法是用三个反引号包裹，并且必须指定语言：

```javascript
const greeting = (name) => `Hello, ${name}!`;
console.log(greeting("World"));
```

```python
def greeting(name: str) -> str:
    return f"Hello, {name}!"
```

```bash
# 安装依赖
npm install && npm run build
```

指定语言有三个好处：语法高亮、代码可读性提升、屏幕阅读器识别代码类型。不写语言标识符是最常见的懒惰写法，请改掉这个习惯。

任务列表（GFM）

## 上线前检查清单

- [x] 代码 Review 完成
- [x] 单元测试通过
- [ ] 性能测试
- [ ] 安全扫描
- [ ] 文档更新

任务列表在 GitHub Issues、Notion、Obsidian 中都可以交互式勾选。

脚注

Markdown 由 John Gruber 创建于 2004 年[^1]，是目前最流行的轻量级标记语言。

[^1]: John Gruber, "Markdown", https://daringfireball.net/projects/markdown/

脚注适合学术写作或需要引用来源的文章，渲染后会在页面底部生成带编号的注释。

GFM 表格

| 工具 | 平台 | 免费 | 协作 |
|------|------|:----:|:----:|
| Obsidian | 桌面/移动 | ✅ | 有限 |
| Notion | Web/桌面 | ✅ | ✅ |
| HackMD | Web | ✅ | ✅ |
| Typora | 桌面 | ❌ | ❌ |

冒号控制对齐：--- 默认左对齐，:---: 居中，---: 右对齐。

写作最佳实践

1. 标题层级严格规范

错误做法：在正文中使用 # 一级标题；跳级使用（从 h2 直接跳 h4）。正确做法：正文从 ## 开始，层级连续，不跳级。这不只是美观问题，屏幕阅读器依赖标题层级导航，SEO 爬虫也会解析标题结构。

2. 图片必须写 alt 文字

<!-- 错误：alt 为空 -->
![]( /images/architecture.png)

<!-- 正确：描述图片内容 -->
![系统架构图：三层架构，包含前端、API 网关和数据库层](/images/architecture.png)

Alt 文字有两个作用：图片加载失败时显示替代文字；搜索引擎通过 alt 理解图片内容。写 alt 的原则：用一句话描述图片传达的核心信息，而不是"图片"或"截图"这类无意义文字。

3. 行长度控制

在纯文本编辑器中，建议每行不超过 80~100 个字符（英文），中文可以适当放宽。这样的好处是：git diff 时每行变化清晰可见；在终端中阅读不需要横向滚动。

在 VS Code 中可以开启竖线提示：

"editor.rulers": [80, 120]

4. 文件命名规范

Markdown 文件命名推荐全小写、用连字符分隔：

markdown-best-practices.md    ✅
MarkdownBestPractices.md      ❌
markdown best practices.md    ❌（空格在 URL 中需要编码）

跨平台兼容性注意事项

特性	GitHub	Notion	Obsidian	Hugo/Jekyll
GFM 表格	✅	✅	✅	需插件
任务列表	✅	✅	✅	需插件
脚注	✅	❌	✅	依主题
HTML 内联	✅	❌	部分	✅
数学公式	有限	✅	✅(插件)	需配置
Wiki 链接	❌	✅	✅	❌

建议：如果文章需要跨平台发布，避免使用平台特有语法，坚守 CommonMark + GFM 核心特性。

工具推荐

在线编辑器

MagicTools Markdown 编辑器：支持实时预览和分享链接
HackMD：团队协作 Markdown，支持版本历史

VS Code 插件

Markdown All in One：快捷键、目录生成、格式化
Markdown Preview Enhanced：强大的预览，支持数学公式、图表
markdownlint：实时检查格式规范，防止写出不规范的语法

桌面客户端

Obsidian：知识管理神器，双向链接、图谱视图，免费本地使用
Typora：所见即所得，边写边渲染，付费但体验极佳

FAQ

Q：Markdown 能替代 Word 吗？

A：对技术写作场景（文档、博客、README）完全可以替代。但对需要复杂排版（精确页边距、分栏、图文混排）的场景，Word/InDesign 仍有优势。Markdown 的核心价值是"内容与样式分离"——专注写内容，样式交给渲染引擎。

Q：如何在 Markdown 中插入数学公式？

A：大多数支持数学公式的 Markdown 平台使用 LaTeX 语法，用 $...$ 表示行内公式，$$...$$ 表示块级公式：

行内公式：质能方程 $E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

GitHub 原生支持这种语法（2022 年起），Obsidian 和大多数静态博客框架也支持，但需要确认平台配置了 MathJax 或 KaTeX 渲染引擎。

Q：Markdown 文件如何转 PDF？

A：有三种主流方式：第一，浏览器打印法——在支持 Markdown 预览的工具（如 VS Code 预览、MagicTools）中打开，按 Ctrl+P → 打印到 PDF，简单但样式依赖浏览器。第二，Pandoc 命令行——pandoc input.md -o output.pdf，需要安装 LaTeX 环境，输出质量最高，适合正式文档。第三，在线工具——如 MagicTools 的导出功能，一键导出，适合临时需求。

总结

Markdown 的学习曲线很平缓，但要用好它需要养成一些习惯：规范标题层级、始终为代码指定语言、为图片写有意义的 alt 文字。掌握 GFM 扩展特性（表格、任务列表、脚注）可以让你的文档表达力大幅提升。

最重要的是选择一个好的工作流：本地用 Obsidian 或 VS Code 写，配合 Git 版本管理，发布时使用合适的转换工具。一旦养成这套习惯，Markdown 会成为你写作效率提升最显著的工具之一。