Markdown 基础语法

创建日期：2026/9/22最后更新：2026/10/16字数：2121阅读时间：5 分钟

Markdown 是一种轻量级标记语言。它使用纯文本格式编写文档，可与 HTML 混编，可导出多种格式的文件。简洁、高效、易读、易写。

在线体验一下 Markdown 在线编辑器。

千万不要被「标记」「语言」吓到，Markdown 的语法十分简单，常用的标记符号不超过十个，用于日常写作记录绰绰有余，不到半小时就能完全掌握。

以 CommonMark 为准

Markdown 由 John Gruber 在 2004 年创造，但它从未有过正式规范，各家实现（GitHub、Typora、Obsidian、各类博客框架）各自方言化，同一个写法在不同地方渲染结果可能不一样，这是新手困惑的主要来源。

CommonMark 是 2014 年启动的标准化工作，它把 Markdown 的每条语法都写成了可测试的规范（现行版本 0.31.2），如今已是事实标准：GitHub、VitePress、VS Code、Obsidian 等都基本遵循它。本站同样遵循 CommonMark。

因此本站把语法分成两篇：

本篇（基础语法）：只讲 CommonMark 明确规定的写法，这些在任何地方都一致，学会了就不会错；
常见扩展语法：表格、删除线、任务列表、脚注、公式等。它们很常用，但不是标准，各家支持情况不一。

两条贯穿全文的规则

空行决定结构。Markdown 靠空行区分「这一个块」和「下一个块」，很多诡异的渲染结果都是少了（或多于）一个空行。
标记符号必须是半角。中文输入法下的全角标点 ，。？！（）【】：；"" 不被 Markdown 认可，**（粗体）** 是不会生效的。

段落与换行

段落由一个或多个空行分隔。源码里的单个换行只是「软换行」，渲染时会被折叠成一个空格——这一点和 Word 很不一样，是最容易踩的坑。

这是第一段的第一行。
这一行和上一行在同一段里，中间只有一个换行。

这是第二段。

这是第一段的第一行。这一行和上一行在同一段里，中间只有一个换行。

这是第二段。

硬换行

确实需要换行（而不是新起一段）时，在行尾加两个及以上空格，或在行尾写一个反斜杠 \：

第一行末尾有两个空格  
第二行

第三行末尾有反斜杠\
第四行

第一行末尾有两个空格
第二行

第三行末尾有反斜杠
第四行

写法	HTML	说明
空行分隔	`<p>…</p><p>…</p>`	新起一段，段间距较大
行尾两个空格	`<br>`	段内换行，最常用
行尾 `\`	`<br>`	同上，可见性更好

标题

ATX 标题

在标题文字前加 1–6 个 #，# 的数量就是标题级别。# 与文字之间建议加一个空格（不加也能渲染，但个别实现不认，且不加空格时 #hashtag 这类内容会被误判）。

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

标题可缩进最多三个空格；
行尾可以加任意数量的 # 作「闭合」，渲染时不显示（## 标题 ## 与 ## 标题 等价）；
本页各级标题的效果就是上面写法的渲染结果。

Setext 标题

在文字下方加一行 =（一级）或 -（二级）。这种写法只支持两级，好处是源码里更醒目：

这是一级标题
============

这是二级标题
------------

- 会引发歧义

下一节的「分隔线」也用 ---。当 --- 紧跟在一行文字下面时，它优先被解释为 Setext 二级标题；只有它上方是空行时才渲染成分隔线。想画分隔线，务必在它前后都留空行。

强调

斜体

在文字前后各加一个 *（星号）或 _（下划线）。

Markdown	HTML	渲染效果
`斜体`	`<em>斜体</em>`	斜体
`_斜体_`	`<em>斜体</em>`	斜体
`abc`	`a<em>b</em>c`	abc

粗体

在文字前后各加两个 * 或 _。

Markdown	HTML	渲染效果
`粗体`	`<strong>粗体</strong>`	粗体
`__粗体__`	`<strong>粗体</strong>`	粗体
`加粗中间`	`加<strong>粗</strong>中间`	加粗中间

本站的粗体带一条色带

本站给 **粗体** 额外加了一条底部色带（与马克笔同色），这是站点样式而非 Markdown 标准行为，详见本站特有的 Markdown 语法。

粗斜体

前后各三个 *（或 _），即粗体与斜体的叠加：

Markdown	HTML	渲染效果
`*粗斜体*`	`<strong><em>粗斜体</em></strong>`	粗斜体
`_粗斜体_`	`<strong><em>粗斜体</em></strong>`	*粗斜体*

`*`、`_` 的区别与三条硬性规则

两种符号在大多数场合等价，但 CommonMark 规定了三条容易翻车的细则：

_ 不能在单词内部生效。写 snake_case_name 不会把中间变斜体（正是为了避免误伤变量名）；* 可以，所以强调单词的一部分时应改用 *。
标记内侧不能直接跟空格。* 这不是斜体 * 无效，要写成 *这是斜体*。
标记必须成对。单个孤立的 * 会原样显示。

列表

无序列表

每行前面加 -、* 或 + 三种标记之一，标记后至少跟一个空格。三种标记可以混用，但同一份文档里建议统一。

- 第一项
- 第二项
- 第三项
  - 缩进后可嵌套子项
  - 子项第二行
- 第四项

第一项
第二项
第三项
- 缩进后可嵌套子项
- 子项第二行
第四项

有序列表

每行前面加「数字 + . 或 )」。数字不必连续，但按 CommonMark，列表的起始数字会被保留——第一项写 3.，渲染就从 3 开始计数。

1. 第一项
2. 第二项
3. 第三项
   1. 嵌套的有序子项
   2. 子项二
4. 第四项

第一项
第二项
第三项
1. 嵌套的有序子项
2. 子项二
第四项

起始数字各家不一致

部分实现会忽略起始数字、一律从 1 开始（本站按 CommonMark 保留）。要避免争议，就从 1. 开始写。

列表里嵌套其他块

列表项下要放段落、引用、代码块时，把内容缩进到与列表项文字左对齐的位置（通常 2 或 4 个空格）。紧邻的空行也要一并缩进。

1.  第一项

    这是属于第一项的第二段，缩进到与「第」字对齐。

2.  第二项

    > 引用块也能放进列表项。

    ```
    代码块同理
    ```

3.  第三项

项与项之间是否空行，还会影响排版密度：不留空行是「紧凑列表」，留了空行则每项内容会被包成段落、间距更大。

引用

在段落前加 >（> 后建议跟一个空格）创建块引用。

> 这是一段引用。

这是一段引用。

多段落引用：段落之间的空行也要加 >。

> 第一段引用。
>
> 第二段引用。

第一段引用。
第二段引用。

嵌套引用：用 >>（也可以写成 > >）。

> 外层引用。
>
> > 内层引用。

外层引用。
内层引用。

懒延续：引用内的后续段落可以省略 >，只要没有空行打断，就仍算引用内容。这是 CommonMark 的规定，但可读性差，写作时建议每行都写 >。

引用里可以放标题、列表、强调等几乎所有 Markdown 元素：

> #### 引用里的标题
>
> - 列表项一
> - 列表项二
>
> *斜体* 与 **粗体** 同样有效。

代码

行内代码

用一对反引号 ` 包围。反引号内的内容原样显示，不会被当作 Markdown 解析——这也是在正文里展示标记符号的办法。

Markdown	HTML	渲染效果
按 `Ctrl` 键	`按 <code>Ctrl</code> 键`	按 `Ctrl` 键

内容里本身就含反引号时，用两对反引号包围：

``含 ` 反引号``

渲染为含 ` 反引号。

代码块

围栏代码块最常用：上下各一行三个反引号 ```（或三个波浪号 ~~~）。开头那行的反引号后面可以写语言名（info string），用于语法高亮：

```python
def hello():
    print("Hello, NKUwiki!")
```

渲染为：

python

def hello():
    print("Hello, NKUwiki!")

闭合围栏要单独一行，长度不能短于开启的那行；
围栏整体可缩进最多三个空格（便于放进列表项）；
语言名写 text 或留空则不做高亮。

缩进代码块是 CommonMark 的原始写法：每行缩进四个空格（或一个 tab）。它不够直观，且与列表缩进容易混淆，日常写作推荐用围栏。

    这行缩进四空格，会渲染成代码块。

分隔线

单独一行写三个或以上的 *、- 或 _，中间可插空格：

***

---

___

三者渲染结果完全一样：

两种失效情形

--- 上方紧跟文字（无空行）→ 变成 Setext 二级标题；
--- 位于表格的第二行 → 是表格语法的一部分，不是分隔线。

保险做法：分隔线上下各留一个空行。

链接

行内链接

链接文字放中括号，地址放紧跟的括号里，括号内地址后可加可选的标题（鼠标悬停时显示）：

[Markdown 语法](https://markdown.com.cn "最好的 Markdown 教程")

Markdown 语法

对应 HTML：<a href="https://markdown.com.cn" title="最好的 Markdown 教程">Markdown 语法</a>。

引用式链接

链接定义可以集中放在文档任意位置（通常放在文末），正文只写标签，适合正文里多次引用同一地址、或正文要塞很多长链接的场合：

投稿前请先读[贡献指南][contributing]，选课相关看[选课][course]。

[contributing]: /pages/Contributing/ "如何投稿"
[course]: /pages/CourseSelection "选课"

[文字][标签]、简化写法 [标签][]、快捷写法 [标签] 三种都可以；
标签不区分大小写，内部连续的空白会被折叠成一个空格；
定义行本身不会渲染出来。

自动链接

用尖括号包围网址或邮箱，会直接变成可点击链接，且显示文本就是地址本身：

<https://www.nankai.edu.cn/>
<nkumail@example.com>

https://www.nankai.edu.cn/

nkumail@example.com

裸网址是扩展，不是标准

直接写 https://… 就自动变链接，属于 GFM 扩展，CommonMark 并不支持。本站支持，但换到其他环境可能不生效——需要确保万无一失时用尖括号。

链接的几个细节

链接文字可以带格式：[**粗体链接**](地址)、[代码链接](地址) 都合法；
地址里的空格用 %20 代替：[link](https://example.com/my%20page)。直接写空格各家处理不一；
站内链接写绝对路径：本站用 /pages/xxx/ 这种以斜杠开头的写法，见贡献指南。

图片

图片语法就是在链接前加一个 !，方括号里是替代文本（alt）：

![马蹄湖的荷花](/map/pic/xxx.png "拍摄于七月")

对应 HTML：<img src="/map/pic/xxx.png" alt="马蹄湖的荷花" title="拍摄于七月">。

alt 要认真写：图片加载失败时显示这段文字，屏幕阅读器也靠它朗读，是 accessibility 的基本要求；
图片同样支持引用式写法：![替代文本][img]，文末再写 [img]: /img/xx.png；
图片外套一层链接即可「点击图片跳转」：[![替代文本](/img/xx.png)](https://…)。

本站的图片

放在 docs/public/ 下的图片可直接以 / 开头的路径引用；正文里的图片点击可全屏预览。详见贡献指南。

转义与特殊字符

反斜杠转义

在任意 ASCII 标点前加 \，可让它当作普通字符显示，不被解析为语法。常用的是这些：

想显示	写法	想显示	写法
`*`	`\*`	`#`	`\#`
`_`	`\_`	`	\`
`[` `]`	`\[` `\]`	`>`	`\>`
`-` `+` `.`	`\-` `\+` `\.`	`\`	`\\`

不转义会变成斜体：*文字*
转义后原样显示：\*文字\*

不转义会变成斜体：文字转义后原样显示：*文字*

反斜杠只在「可能被解析成语法的地方」起作用；在代码块和行内代码里它就是一个普通字符。

字符实体

HTML 的实体与数字字符引用同样可用，适合输入 Markdown 语法字符之外的特殊符号：

写法	显示
`&`	&
`<` `>`	< >
`©`	©
`#`	#
`✓`	✓

行内 HTML

CommonMark 允许在 Markdown 里直接写 HTML 标签，例如   强制换行、H2O 之类。

但本站是静态站点，出于安全与样式一致性考虑，投稿请优先用 Markdown 原生写法；确有需要时，站内提供的 Vue 组件（图片画廊、卡片等）见本站特有的 Markdown 语法。

常见误区速查

现象	原因	怎么办
语法写了没效果	用了全角标点或全角括号	切成半角符号
想换行却没换	单个换行只是软换行	行尾加两个空格，或用空行分段
正文莫名变成了代码块	行首缩进了四个空格	段落不要缩进
`---` 变成了大号标题	被解释为 Setext 二级标题	分隔线前后留空行
`snake_case` 没变斜体	`_` 在单词内部不生效	改用 `*`，或本就不需要强调
有序列表编号不对	起始数字被保留	从 `1.` 开始写
列表/引用「粘」在一起	少了一个空行	两个块之间补空行

组织详情

校园建筑

学校系统

日常生活

Markdown

Markdown 基础语法

以 CommonMark 为准

段落与换行

硬换行

标题

ATX 标题

Setext 标题

强调

斜体

粗体

粗斜体

`*`、`_` 的区别与三条硬性规则

列表

无序列表

有序列表

列表里嵌套其他块

引用

代码

行内代码

代码块

分隔线

链接

行内链接

引用式链接

自动链接

链接的几个细节

图片

转义与特殊字符

反斜杠转义

字符实体

行内 HTML

常见误区速查

参考文献

评论

页面历史

Markdown 基础语法 ​

以 CommonMark 为准 ​

段落与换行 ​

硬换行 ​

标题 ​

ATX 标题 ​

Setext 标题 ​

强调 ​

斜体 ​

粗体 ​

粗斜体 ​

*、_ 的区别与三条硬性规则 ​

列表 ​

无序列表 ​

有序列表 ​

列表里嵌套其他块 ​

引用 ​

代码 ​

行内代码 ​

代码块 ​

分隔线 ​

链接 ​

行内链接 ​

引用式链接 ​

自动链接 ​

链接的几个细节 ​

图片 ​

转义与特殊字符 ​

反斜杠转义 ​

字符实体 ​

行内 HTML ​

常见误区速查 ​

参考文献 ​

评论

页面历史

Markdown 基础语法

以 CommonMark 为准

段落与换行

硬换行

标题

ATX 标题

Setext 标题

强调

斜体

粗体

粗斜体

`*`、`_` 的区别与三条硬性规则

列表

无序列表

有序列表

列表里嵌套其他块

引用

代码

行内代码

代码块

分隔线

链接

行内链接

引用式链接

自动链接

链接的几个细节

图片

转义与特殊字符

反斜杠转义

字符实体

行内 HTML

常见误区速查

参考文献