Markdown 高级用法和最佳实践：从基础语法到工程化写作的全攻略

你是不是以为 Markdown 就是加粗、列表和链接？

我刚开始学 Markdown 的时候也是这么想的。后来写项目文档、技术博客、会议纪要，才发现 Markdown 的花样多得超乎想象。

表格对齐可以手动调，任务列表能做 TODO 管理，内嵌 HTML 可以做出花，甚至数学公式、脚注、自定义属性这些高级用法，都能用纯文本搞定。

今天这篇把 Markdown 从入门到精通的路径梳理一遍。看完你写文档的速度能翻倍。

一、基础语法快速回顾

先过一遍最常见的用法，不熟悉的可以快速扫一眼。

标题用井号，从 H1 到 H6：

# 一级标题
## 二级标题
### 三级标题

加粗用双星号，斜体用单星号：

**这是加粗**
*这是斜体*
***这是加粗斜体***

列表用连字符或数字：

- 无序列表项 1
- 无序列表项 2
  - 缩进表示子列表

1. 有序列表项 1
2. 有序列表项 2

代码块用三个反引号：

```python
def hello():
    print("world")
```

这些内容你大概率已经熟了。接下来才是这篇的重点。

二、实用但不常用的语法

任务列表（Todo List）

在列表前面加 [ ] 或 [x]，就变成任务列表：

- [ ] 完成文档初稿
- [x] 搭建项目骨架
- [ ] 编写单元测试
- [x] 配置 CI/CD 流水线

渲染出来会有复选框。标记 [x] 的就是已完成。

这个功能在 GitHub README、项目 TODO 文件、会议记录里特别好用。一眼就能看出哪些事还没做完。

删除线

用两个波浪线：这是删除的内容。

代码评审里经常用到：

// TODO: 重构这个函数（已标记，等下个迭代处理）

引用块嵌套

引用可以嵌套多层，适合长引用或者引用中引用：

> 外层引用
> > 内层引用
> 回到外层

自动链接

在文字外面包一对尖括号，会自动变成可点击的链接：

<https://navbox.com.cn>
<email@example.com>

写技术文档时，不需要在链接文字和 URL 之间做区分，直接放链接就好。

转义字符

想在 Markdown 里显示特殊字符？前面加反斜杠：

\*这不是斜体\*
\# 这不是标题
\--- 这不是分割线

三、表格的高级用法

表格是 Markdown 里最复杂的语法之一，但用好能省去大量排版时间。

基础表格

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 数据1  |   数据2  |    数据3 |
| 数据4  |   数据5  |    数据6 |

冒号控制对齐方式：左边冒号=左对齐，两边都有=居中，右边冒号=右对齐。

表格中的代码

表格里放代码块会很麻烦，因为代码块需要三个反引号，而表格内部解析优先级更高。

解决方案：用行内代码（单个反引号）代替多行代码块，或者把代码块放到表格外面：

| 功能 | 语法 |
|------|------|
| 加粗 | `**文字**` |
| 斜体 | `*文字*` |

表格合并（使用 HTML 混排）

标准 Markdown 不支持表格单元格合并。需要的话，直接在 Markdown 里写 HTML：

<table>
  <tr>
    <th colspan="2">合并单元格</th>
    <th>普通</th>
  </tr>
  <tr>
    <td>A</td>
    <td>B</td>
    <td>C</td>
  </tr>
</table>

在技术文档里，如果表格需要合并，这是唯一的 Markdown 方案。

四、内嵌 HTML

Markdown 的核心理念是用纯文本写格式，但它并不禁止你写 HTML。任何 Markdown 渲染器都支持内嵌 HTML。

图片添加 alt 和 title

![alt 文字](/image.png "鼠标悬浮时显示的提示文字")

行内样式

想让某段文字变色？Markdown 做不到，但 HTML 可以：

<span style="color: red;">危险操作，请谨慎</span>

自定义属性

Markdown 的属性扩展语法支持自定义属性，用花括号包裹：

{.highlight .important}
这是一段标记的文本

渲染时会自动加上 class="highlight important"。在博客和文档站里做高亮标注非常有用。

iframe 嵌入

<iframe src="https://example.com" width="100%" height="400"></iframe>

写教程文档时可以直接嵌入在线演示，读者不用离开页面就能看到效果。

五、数学公式

支持 LaTeX 语法，行内公式用 $ 包裹，独立公式用 $$ 包裹：

行内公式：$E = mc^2$

独立公式：

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

GitHub 原生不支持数学公式，但很多文档站（如 GitBook、Vercel Docs）都通过插件支持。写技术博客时，数学公式能让复杂的概念一目了然。

六、脚注

脚注适合需要补充说明但不想打断正文阅读的场景：

Markdown 是一种轻量级标记语言[^1]。

[^1]: 由 John Gruber 于 2004 年创建。

渲染后，标注处会有一个上标数字，脚注内容显示在页面底部。写学术论文和技术文档时很实用。

七、信息面板（Admonition）

信息面板是一种特殊的引用块，用来突出显示重要信息。语法因渲染器而异，通用的写法是：

> [!NOTE]
> 这是一个提示信息。

> [!TIP]
> 这是一个操作建议。

> [!WARNING]
> 这是一个警告信息。

> [!DANGER]
> 这是一个危险提示。

GitHub Flavored Markdown 原生支持这种语法。渲染后会有不同颜色的背景和图标，分别对应提示、建议、警告和危险。

写 API 文档、项目 README 时，信息面板能让重要内容一眼被注意到。

八、工程化 Markdown 写作

光会语法还不够。要把 Markdown 用到极致，还需要工程化的思路。

1. 文件组织

项目文档建议用目录结构组织：

docs/
├── README.md          # 项目概述
├── getting-started.md # 快速开始
├── api/
│   ├── README.md
│   ├── users.md
│   └── posts.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

每个目录放一个 README 作为索引，方便浏览和导航。

2. 代码片段复用

长文档里的代码片段不要重复写。用引用外部文件的方式：

部分渲染器支持：

@[include](./config-example.js)

这样改一次代码示例，所有引用它的文档都会更新。

3. 写作工作流优化

在 VS Code 或 Cursor 里写 Markdown，有几个插件/技巧能大幅提升效率：

• Markdown Preview Enhanced：实时预览 + 表格编辑器
• Markdown All in One：自动标题编号、快捷键、表格生成
• Cursor 的 Ctrl/Cmd + K：写文档时让 AI 帮你润色、补全、翻译

4. 笔记管理策略

个人笔记推荐用 Markdown 文件管理，配合 Obsidian 或 VS Code：

• 每个主题一个文件
• 用 [[双链]] 连接相关笔记
• 用标签 #标记分类
• 定期整理归档

Markdown 作为笔记格式的最大优势是可移植性。不管用什么工具打开，文字和格式都不会乱。不像 Notion 或 Obsidian 的数据库，换了平台数据就很难迁移。

九、不同渲染器的差异

这是很多人踩坑的地方。Markdown 没有官方标准，不同平台对语法的支持程度不一样。

写作时建议以目标平台的语法为准。如果你的文档最终放在 GitHub 上，就别用脚注——GitHub 不支持。如果放在技术博客上，数学公式和信息面板都能用上。

十、Markdown 在线工具的配合使用

写 Markdown 时配合在线工具能提升很多效率：

• navbox 的 Markdown 在线预览：写完实时预览渲染效果，调试表格和代码块排版
• JSON 格式化：Markdown 文档里经常要贴 JSON，先格式化再粘贴，排版更整齐
• Base64 编码解码：图片转 Base64 直接内嵌到 Markdown 里

工具配好了，写文档就像搭积木一样顺畅。

总结

Markdown 看起来简单，深挖下去有很多实用的技巧。

• 日常写作：记住任务列表、删除线、转义字符这三样，日常够用
• 文档写作：学会表格、信息面板、内嵌 HTML，能写出专业级别的文档
• 技术写作：掌握数学公式、脚注、代码片段复用，写论文和教程更轻松
• 笔记管理：Markdown 文件 + 双链工具 = 可移植的个人知识库

从这篇的某个小技巧开始试试，下次写文档时你会发现，原来 Markdown 比你想的要强大得多。