Markdown 完整指南:语法、技巧与最佳实践

· 12分钟阅读

目录

什么是 Markdown?

Markdown 是由 John Gruber 与 Aaron Swartz 于2004年合作创建的轻量级标记语言。它让你使用纯文本语法编写格式化文本,即使不渲染也保持可读性。你无需在文字处理器中点击按钮或编写冗长的 HTML 标签,只需使用简单直观的字符,如用 # 表示标题、** 表示粗体文本、- 表示列表。

Markdown 背后的理念优雅而简单:源文本应该与渲染输出一样可读。当你在任何文本编辑器中打开 Markdown 文件时,无需特殊软件或渲染引擎就能立即理解其结构和内容。

Markdown 已成为技术写作、文档、README 文件、博客文章和笔记的事实标准,遍布整个软件开发领域。GitHub、GitLab、Reddit、Stack Overflow、Discord、Slack、Notion 和 Obsidian 等主要平台都原生支持 Markdown,使其成为开发者、技术作家和内容创作者的必备技能。

为什么使用 Markdown?

专业提示: 如果你经常使用 Markdown 文件,可以试试我们的 Markdown 编辑器 进行实时预览和语法高亮,或使用 Markdown 转 HTML 转换器 即时转换文档。

标题和文档结构

标题是 Markdown 文档结构的支柱。它们使用 # 符号,井号数量决定标题级别,从1到6:

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

始终在 # 符号后包含一个空格——大多数 Markdown 处理器需要它,这也能提高可读性。渲染输出会创建正确的 HTML 标题标签(<h1> 到 <h6>),这对文档结构、可访问性和 SEO 至关重要。

标题最佳实践

按顺序使用标题级别,不要跳过级别。不要从 H1 跳到 H3——这会破坏文档层次结构,并为屏幕阅读器用户造成可访问性问题。将标题视为大纲:每个级别应该在逻辑上嵌套在前一个级别中。

大多数文档应该只有一个 H1 标题(标题),H2 标题用于主要部分,H3-H6 用于子部分。这创建了清晰的信息层次结构,人类和搜索引擎都能理解。

快速提示: 许多 Markdown 处理器会自动为标题生成锚点链接,允许你直接链接到特定部分。例如,GitHub 会将 "## 入门指南" 转换为可以用 #入门指南 引用的锚点。

替代标题语法

Markdown 还支持使用下划线的 H1 和 H2 标题替代语法:

一级标题
=========

二级标题
---------

虽然这种语法有效,但井号语法更常见且支持所有六个标题级别,使其成为大多数作者的首选。

文本格式基础

Markdown 为常见文本格式需求提供简单直观的语法。这些格式选项在段落内内联工作,可以组合使用以实现更复杂的样式。

格式 语法 替代方式 结果
粗体 **粗体** __粗体__ 粗体
斜体 *斜体* _斜体_ 斜体
粗体+斜体 ***两者*** ___两者___ 两者
删除线 ~~删除~~ — 删除
行内代码 `代码` — 代码
下标 H~2~O — H2O
上标 X^2^ — X2
高亮 ==标记== — 标记

强调语法详情

星号(*)和下划线(_)都可用于强调,但星号更常用且推荐使用。关键区别:星号可在单词中间使用(un*frigging*believable),而下划线需要单词边界。

对于粗体文本,使用双星号或双下划线。对于斜体文本,使用单星号或单下划线。组合三个用于粗斜体文本。这种一致性使你的 Markdown 源代码更可读和可预测。

专业提示: 编写技术文档时,对行内代码、函数名、文件路径和命令行参数使用 `反引号`。这种视觉区分帮助读者快速识别文本中的代码元素。

转义特殊字符

如果需要显示字面星号、下划线或其他 Markdown 语法字符,用反斜杠转义它们:

这不是 \*斜体\* 也不是 \*\*粗体\*\*
使用 \# 显示井号而不创建标题

需要转义的常见字符包括:\ ` * _ { } [ ] ( ) # + - . !

列表:有序、无序和嵌套

列表是在 Markdown 中组织信息的基础。它们创建简单,支持嵌套以实现层次化内容。

无序列表

使用 -、* 或 + 后跟空格创建无序(项目符号)列表。这三个标记的工作方式相同,但文档内的一致性可提高可读性:

- 第一项
- 第二项
- 第三项
  - 嵌套项(缩进2个空格)
  - 另一个嵌套项
- 第四项

嵌套列表的标准缩进是两个空格,尽管有些解析器接受四个。坚持使用两个空格以获得最大兼容性。

有序列表

有序(编号)列表使用数字后跟句点和空格:

1. 第一步
2. 第二步
3. 第三步
   1. 子步骤 A
   2. 子步骤 B
4. 第四步

这里有一个有用的特性:你使用的实际数字并不重要。Markdown 在渲染时会自动按顺序重新编号列表。你可以对每一项都使用 1.,这样重新排序项目时无需重新编号:

1. 第一项
1. 第二项
1. 第三项

这会渲染为正确编号的 1、2、3 列表。这种技术在维护长列表或频繁重新排序项目时特别有用。

任务列表

许多 Markdown 变体(包括 GitHub Flavored Markdown)支持带复选框的任务列表:

- [x] 已完成任务
- [ ] 未完成任务
- [ ] 另一个未完成任务

任务列表对于项目管理、问题跟踪和文档中的待办事项列表非常有价值。

快速提示: 要在列表项中包含多个段落或代码块,请缩进后续内容以与列表项文本的第一个字符对齐(无序列表通常为3-4个空格,有序列表为4个空格)。

定义列表

一些扩展的 Markdown 语法支持用于术语表和术语定义的定义列表:

术语 1
: 术语 1 的定义

术语 2
: 术语 2 的第一个定义
: 术语 2 的第二个定义

虽然不是普遍支持,但定义列表对技术文档和术语表很有用。

Markdown 使添加超链接和图片变得简单,同时保持源文本可读。

内联链接

最常见的链接语法使用方括号表示链接文本,圆括号表示 URL:

[链接文本](https://example.com)
[带标题的链接](https://example.com "悬停文本")

可选的标题文本在用户悬停在链接上时显示为工具提示。这对于提供额外上下文而不使可见链接文本混乱很有用。

引用式链接

对于有许多链接或重复 URL 的文档,引用式链接可提高可读性:

这是[一个链接][1],这是[另一个链接][2]。

[1]: https://example.com
[2]: https://example.com/page "可选标题"

你也可以使用描述性引用而不是数字:

查看 [Google][google] 和 [GitHub][gh]。

[google]: https://google.com
[gh]: https://github.com

引用定义可以出现在文档的任何位置,不会在输出中渲染。许多作者将它们放在章节末尾或文档末尾。

自动链接

用尖括号包裹 URL 或电子邮件地址以创建自动链接:

<https://example.com>
<[email protected]>

大多数现代 Markdown 解析器也会自动将裸 URL 转换为可点击链接,尽管这种行为在所有平台上并不保证。

图片

图片语法与链接语法几乎相同,只是前面有感叹号:

![替代文本](image.jpg)
![替代文本](image.jpg "图片标题")

替代文本对可访问性至关重要——它为屏幕阅读器用户描述图片,并在图片加载失败时显示。始终提供传达图片内容和目的的有意义的替代文本。

引用式语法也适用于图片:

![Logo][logo]

[logo]: /images/logo.png "公司标志"

专业提示: 标准 Markdown 不支持图片大小调整或对齐。对于这些功能,你需要直接使用 HTML:<img src="image.jpg" width="300" alt="描述"> 或依赖特定于你平台的扩展 Markdown 语法。

链接图片

要使图片可点击,将图片语法包装在链接语法中:

[![替代文本](thumbnail.jpg)](full-size.jpg)

这种技术通常用于图片库或将缩略图链接到全分辨率版本。

代码块和语法高亮

Markdown 擅长显示代码,使其成为技术文档和编程教程的首选格式。

行内代码

对于文本中的短代码片段,使用单反引号:

使用 `print()` 函数显示输出。
`config.json` 文件包含设置。

如果你的代码包含反引号,使用双反引号包装它:

``在代码中使用 `反引号` ``

围栏代码块

对于多行代码块,在代码前后使用三个反引号(```)或三个波浪号(~~~):

```
function greet(name) {
  return `Hello, ${name}!`;
}
```

这会创建一个格式正确的代码块,使用等宽字体并保留空白。

语法高亮

在开头反引号后立即指定编程语言以启用语法高亮:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "Hello, World!"
```

支持的语言因平台而异,但常见语言包括 javascript、python、java、c、cpp、csharp、php、ruby、go、rust、sql、html、css、bash、shell、json、xml、yaml、markdown 等。

专业提示: 一些 Markdown 处理器支持代码块中的行号和行高亮。例如,GitHub 允许你使用 ```javascript{1,3-5} 高亮第1行和第3-5行。

缩进代码块

另一种创建代码块的方法是将每行缩进四个空格或一个制表符:

    function greet(name) {
      return `Hello, ${name}!`;
    }

虽然这种方法有效,但围栏代码块更受欢迎,因为它们支持语法高亮且更易于输入。

表格和数据展示

表格不是原始 Markdown 规范的一部分,但大多数现代 Markdown 处理器都支持它们。表格对于以结构化格式呈现数据非常有用。

基本表格语法

使用竖线(|)和连字符创建表格:

| 标题 1 | 标题 2 | 标题 3 |
|--------|--------|--------|
| 单元格 1 | 单元格 2 | 单元格 3 |
| 单元格 4 | 单元格 5 | 单元格 6 |

外部竖线是可选的,你不需要使列完美对齐——Markdown 处理器会处理格式:

标题 1 | 标题 2 | 标题 3
---|---|---
单元格 1 | 单元格 2 | 单元格 3
单元格 4 | 单元格 5 | 单元格 6

列对齐

使用标题分隔行中的冒号控制列对齐:

| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 文本   | 文本     | 文本   |
| 更多   | 更多     | 更多   |

表格中的格式

你可以在表格单元格中使用内联 Markdown 格式:

| 功能 | 状态 | 备注 |
|------|------|------|
| **粗体文本** | ✅ 支持 | 使用 `**` |
| *斜体文本* | ✅ 支持 | 使用 `*` |
| `代码` | ✅ 支持 | 使用反引号 |
| [链接](url) | ✅ 支持 | 标准语法 |

快速提示: 对于复杂表格或需要合并单元格,考虑直接使用 HTML 表格语法。Markdown 表格对于简单的表格数据效果最好。

表格限制

Markdown 表格有一些限制:

对于这些高级功能,你需要使用 HTML 表格或考虑使用不同的文档格式。

引用块和水平分隔线

引用块

使用大于号(>)创建引用块,通常用于引用或突出显示重要信息:

> 这是一个引用块。
> 它可以跨越多行。

引用块可以包含其他 Markdown 元素:

> ## 引用中的标题
>
> - 列表项 1
> - 列表项 2
>
> **粗体文本** 和 *斜体文本* 也可以使用。

嵌套引用块

通过添加额外的 > 符号嵌套引用块:

> 这是第一级引用。
>
> > 这是嵌套引用。
> >
> > > 这是更深层的嵌套。
>
> 回到第一级。

水平分隔线

使用三个或更多连字符、星号或下划线创建水平分隔线(主题分隔):

---

***

___

所有这些都会产生相同的结果。为了可读性,许多作者更喜欢使用三个连字符,并在前后留空行:

第一部分内容。

---

第二部分内容。

专业提示: 谨慎使用水平分隔线。过度使用会使文档看起来支离破碎。它们最适合分隔文档中的主要部分或主题转换。

扩展语法特性

虽然原始 Markdown 规范相对简单,但许多处理器添加了扩展功能。这些功能的可用性因平台而异。

脚注

许多 Markdown 处理器支持脚注:

这是带脚注的文本[^1]。

[^1]: 这是脚注内容。

脚注会自动编号,并在文档末尾呈现,带有返回引用的反向链接。

定义列表

如前所述,一些处理器支持定义列表:

术语
: 定义

表情符号

许多平台支持表情符号简码:

:smile: :heart: :thumbsup:

这些会渲染为实际的表情符号字符:😊 ❤️ 👍

自动链接

大多数现代处理器会自动将 URL 转换为链接:

访问 https://example.com 了解更多信息。

高亮

一些处理器支持使用双等号的文本高亮:

==高亮文本==

下标和上标

一些扩展语法支持下标和上标:

H~2~O (下标)
X^2^ (上标)