Markdown 语法:按用途分类的速查表

Markdown 是带有一些简单标记的纯文本。本页是一份速查表。找到你想做的事,复制示例,就可以开始了。

有些标记在任何地方都能用,有些只能在特定应用中使用。每一节都会说明它属于哪一类:

  • 核心:属于基础标准 CommonMark。几乎在所有地方都能用。
  • GFM:GitHub Flavored Markdown 中的扩展,在 CommonMark 的基础上增加了内容。大多数应用都支持。
  • GitHub 功能:被广泛使用,但不在这两种规范中。请确认你的应用是否支持。

标题(核心)

在行首写一到六个 # 标记,然后加一个空格。# 越多,标题越小。

# Title
## Section
### Subsection

空格很重要。七个 # 标记不是标题。

段落和换行(核心)

空行会开始一个新段落。段落内的单个换行不会断行,文字会接着排下去。

如果想换行而不开始新段落,请在行尾加两个空格或一个反斜杠:

First line\
Second line

粗体、斜体和删除线

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

斜体和粗体属于核心。删除线属于 GFM。如果标记位于单词中间,请使用星号,因为 _ 在单词内部不起作用。

列表

- Apples
- Bananas
  - Green ones
  - Yellow ones

1. Wake up
2. Make tea
3. Read

- [ ] Write the draft
- [x] Send the draft

项目符号可以用 -、+ 或 * 开头。编号列表使用数字加 . 或 )。第一个数字决定列表从几开始。

要嵌套列表,请缩进内层列表,使其与上一项的文字对齐。对于 - Bananas,就是缩进两个空格。

项目符号和编号属于核心。任务列表,即 [ ] 和 [x] 方框,属于 GFM。

链接

[PilcrowMD](https://pilcrowmd.com "Optional title")
<https://pilcrowmd.com>
https://pilcrowmd.com

第一种是行内链接:文字放在方括号中,地址放在圆括号中。第二种是用尖括号括起来的自动链接。两者都属于核心。

第三种是不带任何标记的裸地址。CommonMark 不会把它变成链接。GFM 会,只要地址以 http://、https:// 或 www. 开头。

指向标题的链接

要跳转到同一文件中的某个标题,请链接到它的锚点:

## My first section

[Go to the section](#my-first-section)

这个链接是普通的行内链接。在 GitHub 上,锚点由标题文字生成:字母转为小写,空格变成连字符,其他标点被去掉。第二个相同文字的标题会加上 -1。其他应用可能以同样的方式生成锚点,但这是 GitHub 的规则,所以请自行测试。

图片

与链接类似,前面加一个 !:

![A red apple on a table](apple.jpg)

方括号中的文字是描述(即替代文字)。图片语法属于核心。

引文(核心)

每行以 > 开头:

> The best way to learn is to try.

代码

句子中的一小段代码,请使用单个反引号:

Run `npm test` before you commit.

要在代码中显示反引号,请用双反引号把代码括起来。

对于代码块,请使用三个反引号组成的围栏。在起始围栏后写上语言名称:

```python
print("Hello")
```

围栏也可以用三个波浪号 ~~~ 来写。语言名称是可选的。应用用它来给代码着色。以上全部属于核心。

水平分隔线(核心)

单独一行写三个或更多的 -、* 或 _:

---

请在 --- 上方留一个空行。如果它紧贴在一行文字下方,那行文字就会变成标题。

表格(GFM)

表格需要一个表头行、一个短横线行和若干数据行:

| Fruit  | Price |
|--------|-------|
| Apple  | 1.20  |

表格还有更多规则,例如对齐和转义竖线。请参阅 Markdown 表格:怎么写,怎么读。

转义:把标记显示为文字(核心)

在标记前加一个反斜杠,即可将其显示为普通文字:

\*not italic\*

任何标点符号都可以这样转义。反斜杠在代码内部不起作用。

脚注(GitHub 功能)

This claim needs a source.[^1]

[^1]: Here is the source.

脚注不在 CommonMark 或 GFM 规范中。GitHub 支持它们。脚注文字会出现在页面底部,无论你把它写在文件的什么位置。GitHub 在 wiki 中不支持脚注。

提示块(GitHub 功能)

提示块是在第一行带有标签的引文:

> [!NOTE]
> Useful information the reader should know.

类型有 NOTE、TIP、IMPORTANT、WARNING 和 CAUTION。它们不在这两种规范中。请适度使用。

阅读 Markdown

在纯文本编辑器中,所有这些标记都会保持可见。Markdown 阅读器会把它们变成整洁的页面。

PilcrowMD 在 Android 和 Mac 上显示表格、脚注、GitHub 风格的提示块,以及可跳转到标题的链接。在 Mac 上,它还会显示任务列表。

常见问题

我应该先学哪些 Markdown? 核心标记:标题、粗体、斜体、列表、链接、代码和引文。它们在每个 Markdown 应用中都能用。接下来再加上表格和任务列表,因为大多数应用都支持 GFM。

为什么我的 Markdown 在另一个应用里看起来不一样? 各个应用遵循的规则不同。CommonMark 是基础,GFM 在它之上增加内容,还有一些功能,例如脚注和提示块,不在这两者之中。如果某个标记不起作用,多半是该应用不支持它。

# 和 - 后面一定要加空格吗? 是的。请写成 # Title 和 - Item。没有空格,这一行就仍然是纯文本。

Mac 上同样可用: PilcrowMD Mac 版(测试版)