📘 Markdown 保姆级语法手册

2026-10-13· 约 20 分钟

写在前面：先建立正确认知

Markdown 是一种「轻量级标记语言」（2004 年由 John Gruber 设计）。它用极简的符号代替鼠标排版，输出一份纯文本文件，这份文件同时是：

人类可读：记事本都能打开，不依赖任何软件；
机器可解析：GitHub、语雀、飞书、Typora、VSCode、Obsidian 都能渲染成网页 / PDF / Word；
极低学习成本：核心语法几十个符号，几分钟上手。

文件后缀：.md（也有部分用 .markdown）。

广泛用于：GitHub、掘金、CSDN、Notion、语雀、Typora、Obsidian 等。

⚠️

必须先分清：Markdown 没有「唯一标准」
CommonMark

：最通用的基础标准，所有平台都支持；
GFM（GitHub Flavored Markdown）

：GitHub 扩展的语法（表格、任务列表、删除线、自动链接等），是事实行业标准；
平台私有扩展

：Typora、语雀、飞书、Obsidian 各自加的语法，

换平台可能不生效

。
本手册会

明确标注

每项语法是「通用」还是「扩展」，避免你换平台踩坑。

第一部分：编辑器与工具链

写 Markdown 任何文本编辑器都行，但支持实时预览的工具体验天差地别。按需选择：

工具	类型	适合人群	特点
Typora	桌面端（付费）	新手、写作者	「所见即所得」最丝滑，支持公式、图表、高亮
VSCode	桌面端（免费）	程序员	装 `Markdown Preview Enhanced` 插件后很强
Obsidian	桌面端（免费）	笔记重度用户	双链笔记、本地知识库
语雀 / 飞书	在线	团队协作	云端同步、多人协作
GitHub / GitLab	在线	开发者	README、Issues 默认渲染 Markdown
Notion	在线	全能笔记	块式编辑，兼容 Markdown 快捷键

💡

关键概念

：Markdown 有「源码」和「预览」两种形态 —— 你敲的是符号，看到的是渲染结果。学习时边敲边看预览，最快。

第二部分：核心语法（覆盖 90% 场景）

这是基本功，学完即可写 90% 的文档。

1. 标题

用 # 表示，# 的个数代表级别，共 1～6 级。

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

规则要点：

# 与标题文字之间必须有一个空格，否则部分解析器不识别；
# 标题 ✅，#标题 ❌；
每篇文档建议只用一个一级标题（即文档标题），其余用二级及以下；
标题层级不要跳级（不要从 ## 直接跳到 ####）。

另一种写法（Setext 下划线式，仅 1～2 级）：

一级标题（用 === 下划线）
==================

二级标题（用 --- 下划线）
------------------

⚠️

---

单独成行会被当成「分割线」而不是标题。日常统一用

#

写法最稳妥。

2. 段落与换行

段落：连续文字块，段落之间用一个空行隔开；
软换行（段内换行）：行尾加两个空格再回车；
有些编辑器（如 Typora）直接回车即换行，但纯 Markdown 源码下不生效，跨平台建议用两个空格。

这是第一段。

这是第二段（因为上面空了一行）。

这是同一段内的
强制换行（行尾两个空格  ）

⚠️

新手最常踩的坑

：Markdown 里单个回车

不会

产生新段落（和 Word 的直觉不同）。要分段必须空一行。

3. 文字样式

效果	写法	说明
粗体	`文字` 或 `__文字__`	双星号 / 双下划线
斜体	`文字` 或 `_文字_`	单星号 / 单下划线
粗斜体	`*文字*`	三星号
~~删除线~~	`~~文字~~`	双波浪线（GFM 扩展，通用度高）
== 高亮 ==	`==文字==`	双等号（Typora / Obsidian 等扩展）
下划线	`<u>文字</u>`	HTML 标签
H2O	`H<sub>2</sub>O` 或 `H~2~O`	下标（`~x~` 为部分平台简写）
23=8	`2<sup>3</sup>` 或 `2^3^`	上标（`^x^` 为部分平台简写）
`行内代码`	`code`	反引号包裹

嵌套组合示例：

**粗体里的*斜体*效果**

效果：粗体里的斜体效果

⚠️ 符号与文字之间

不要有空格

：

*斜体*

✅，

* 斜体 *

❌。

4. 列表

4.1 无序列表

用 -、*、+ 任一开头 + 空格：

- 苹果
- 香蕉
- 橙子

4.2 有序列表

用 数字. + 空格。数字不必连续，Markdown 自动重编号；但建议按顺序写，方便阅读源码。

1. 第一步
2. 第二步
3. 第三步

4.3 嵌套列表

子项缩进 2 或 4 个空格（或一个 Tab）：

- 前端
  - HTML
  - CSS
  - JavaScript
- 后端
  1. Java
  2. Python

4.4 列表中的段落（多行补充说明）

在列表项内换行写补充说明时，新段落要缩进对齐（与 - 后的文字对齐），否则列表会断裂：

- 第一项

  这是第一项的补充说明（缩进对齐，属于上一项）。

- 第二项

4.5 任务清单（Todo List）

GFM 扩展，用 - [ ]（未完成）和 - [x]（已完成）：

- [x] 已完成任务
- [ ] 未完成任务
- [ ] 待办事项

多用于 GitHub Issue、PR、项目计划。在支持的平台里可以直接点击勾选。

5. 引用（Blockquote）

用 > 开头，可多行、可嵌套：

> 这是一段引用。
> 这是第一层引用
>
> > 这是嵌套的第二层引用

引用内可包含其他语法（斜体、代码、链接、列表等）：

> **注意：** 引用里也能用 *斜体*、`代码`、[链接](https://example.com)。

⚠️ 引用中间的

空行也要带

>

，否则引用会中断。

6. 代码

6.1 行内代码

用一对反引号 ` 包裹：

请使用 `console.log()` 打印日志。

若代码本身含反引号，用

两个反引号

包裹：

` `

code

` `

。

6.2 代码块（围栏式，推荐）

用三个反引号 ``` 包裹，推荐写明语言以触发语法高亮：

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
hello("World");
```

常用语言标识： javascript、typescript、python、java、go、c、cpp、csharp、bash、shell、sql、html、css、json、yaml、xml、markdown、diff。

6.3 缩进式代码块（旧写法，了解即可）

在每行前加 4 个空格或 1 个 Tab 也能表示代码块，但不推荐—— 不如围栏通用、不支持语法高亮、无语言标识。

6.4 在代码块里展示反引号（嵌套围栏）

代码块里若要展示 ``` 本身，用更多反引号（4 个）包裹外层即可：

````markdown
```python
print("嵌套示例")
```
````

7. 分割线

用三个及以上连续的 -、* 或 _，单独成行：

---

***

___

⚠️ 分割线上方若紧贴文字，可能被误识别为二级标题，建议

上下各空一行

。

8. 链接

8.1 行内式（最常用）

[链接文字](https://www.example.com)

[带悬停提示的链接](https://www.example.com "悬停提示文字")

8.2 参考式（长文管理利器）

URL 不写在正文，集中在文末定义，正文保持干净：

[百度][1] 和 [Google][google] 是常用搜索引擎。

[1]: https://www.baidu.com
[google]: https://www.google.com

8.3 自动链接

<https://www.baidu.com>
<someone@example.com>

8.4 锚点跳转（页内跳转）

[跳转到"表格"一节](#表格)

锚点规则：

标题转锚点：英文小写、空格变 -、去除特殊符号（如 # My Section → #my-section）；
中文标题多数平台直接用标题原文（如 #表格）；
不同平台略有差异。

9. 图片

语法与链接几乎一样，前面多一个 !：

9.1 基本语法

![替代文字](图片地址)

![替代文字](图片地址 "悬停标题")

9.2 本地图片 / 网络图片

![Logo](../images/logo.png)        <!-- 本地相对路径 -->
![风景](https://picsum.photos/200/100)  <!-- 网络图片 -->

9.3 带链接的图片（图片可点击跳转）

[![图片](图片地址)](跳转地址)

9.4 控制尺寸（HTML 写法）

<img src="https://picsum.photos/200/100" width="200" height="100" />

💡

工程建议

：图片统一放在

images/

或

assets/

目录，用相对路径引用，方便文档迁移和版本管理。替代文字永远写上（加载失败时显示）。

第三部分：进阶语法（搞定剩余 9%）

10. 表格

GFM 扩展。用 | 分隔单元格，第二行用 --- 分隔表头：

| 姓名 | 年龄 | 城市 |
| :--- | :--: | ---: |
| 张三 |  25  | 北京 |
| 李四 |  30  | 上海 |

渲染：

姓名	年龄	城市
张三	25	北京
李四	30	上海

对齐方式：

写法	对齐
`:---`	左对齐
`:--:`	居中
`---:`	右对齐

注意事项：

第二行的 --- 分隔行是必须的，不能省；
各行列数要一致；
单元格内写竖线 | 需转义为 \|；
单元格内可放 **粗体**、[链接](url)、`代码`；
单元格内换行用 <br>。

11. 转义字符

想原样显示 Markdown 符号，用反斜杠 \ 转义：

\*这不是斜体*
\# 这不是标题
\[这不是链接](不是链接)

可转义字符清单：

\  `  *  _  {  }  [  ]  (  )  #  +  -  .  !  |  >  <  ~

12. HTML 内嵌

Markdown 允许直接写 HTML—— 这是「万能兜底」，Markdown 语法满足不了时用它：

<div style="color: red;">红色文字</div>

<details>
  <summary>点击展开</summary>
  隐藏内容……
</details>

<br>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

常用标签： <br> 换行、<kbd> 按键样式、<sub>/<sup> 上下标、<div> 块容器、<details>/<summary> 折叠块、<img width="300"> 图片尺寸。

⚠️

GitHub 的 README 会过滤部分 HTML 和内联样式

，需谨慎使用；语雀、飞书支持度也不同。

13. 脚注

部分平台（GitHub、Typora、Obsidian）支持：

这是一句话，后面有脚注。[^1]

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

💡 适合论文、长文做补充说明，但并非所有在线笔记都支持，正式文档前先确认。

14. 目录 TOC

自动目录标记： 部分编辑器支持直接写 [TOC] 自动生成目录：

[TOC]

手动写锚点目录：

- [标题一](#标题一)
- [标题二](#标题二)

⚠️

GitHub 默认不渲染

[TOC]

标记

；Typora、语雀、掘金、Obsidian 支持。长文在 GitHub 上建议手写锚点目录。

15. 数学公式（LaTeX）

用 LaTeX 语法， $...$ （行内）或 $$...$$（块级）：

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

块级公式：
$$
\int_{a}^{b} f(x)\ dx = F(b) - F(a)
$$

常用示例：

需求	写法
分数	$\frac{a}{b}$
根号	$\sqrt{x}$
求和	$\sum_{i=1}^{n} i$
希腊字母	$\alpha, \beta, \gamma$
矩阵	$\begin{matrix} a & b \\ c & d \end{matrix}$

💡 支持情况：Typora、Obsidian、掘金、CSDN 支持；GitHub 已原生支持基础

$...$

渲染。复杂宏包各平台差异大，建议实测。

16. Mermaid 图表

用文字描述图表，GitHub、GitLab、语雀、Typora 均支持。

流程图：

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
```

时序图：

```mermaid
sequenceDiagram
    用户->>服务器: 发送请求
    服务器-->>用户: 返回响应
```

饼图：

```mermaid
pie title 水果销量
    "苹果" : 40
    "香蕉" : 30
    "橙子" : 30
```

💡 还支持甘特图、类图、状态图、ER 图等，需要时再深入。

17. Emoji 表情

两种方式：

直接粘贴 Unicode 字符（任何平台都显示）：😀 🚀 🎉 ❤️ ⚠️ 💡 ✅ ⭐ 🔥；
:emoji: 短代码语法（GitHub、GitLab、Slack、部分平台支持）：

:smile: :rocket: :tada: :heart:

常用 Emoji 速查：

短代码	效果	短代码	效果
`:smile:`	😀	`:heart:`	❤️
`:rocket:`	🚀	`:tada:`	🎉
`:warning:`	⚠️	`:bulb:`	💡
`:white_check_mark:`	✅	`:x:`	❌
`:star:`	⭐	`:fire:`	🔥

💡 想在其他平台也稳显示，

直接粘贴 Unicode 表情最保险

；完整短代码表可搜「emoji cheat sheet」。

第四部分：效率、规范与避坑

18. 常用快捷键

Typora / VSCode 等编辑器通用（Windows 用 Ctrl，macOS 用 Cmd）：

操作	快捷键
加粗	`Ctrl/Cmd + B`
斜体	`Ctrl/Cmd + I`
插入链接	`Ctrl/Cmd + K`
插入代码块	`Ctrl/Cmd + Shift + K`
插入行内代码	Ctrl/Cmd + `` ``
标题 1~6	`Ctrl/Cmd + 1~6`
无序列表	`Ctrl/Cmd + Shift + ]`
有序列表	`Ctrl/Cmd + Shift + [`
引用	`Ctrl/Cmd + Shift + Q`
表格	`Ctrl/Cmd + T`

19. 写作规范建议

标题层级清晰：一级标题只用一个，层级不跳级、不超过 4 层；
段落之间空一行：避免渲染错乱；
代码块标明语言：便于高亮，提升可读性；
图片用相对路径：方便迁移与版本管理；
中英文之间加空格：使用 Markdown 写作 比 使用Markdown写作 更易读；
善用引用与列表：结构化表达，读者更易理解；
统一风格：列表统一用 -，粗体统一用 **；
提交前预览：不同平台渲染差异大，发出去前务必预览一遍。

20. 常见问题 FAQ

Q1：为什么我的换行没生效？

Markdown 把单个回车当作空格。请在行尾加两个空格，或直接空一行分段。

Q2：为什么 # 没变标题？

# 与文字之间必须有空格：# 标题 ✅，#标题 ❌。

Q3：表格为什么渲染不出来？

检查分隔行 | --- | --- | 是否存在、每行列数是否一致。

Q4：图片为什么显示不出来？

检查路径、大小写、文件名是否含中文或空格；网络图片检查链接是否可直接访问。

Q5：为什么有的语法不生效？

不同平台支持范围不同（如 GitHub 不渲染 [TOC]、部分平台不支持 ==高亮==），需查阅目标平台文档。

Q6：如何写一个反引号？

用双反引号包裹： ` 。

Q7：如何在表格里写竖线 |？

用 \| 转义。

Q8：Markdown 和 HTML 能混用吗？

可以，绝大多数平台支持；但部分平台（如 GitHub README）会过滤部分 HTML。

21. 常见坑速查表

坑	现象	解决
换行不生效	敲了回车还是一段	段间空一行 / 行尾两空格
标题不生效	`#标题` 没变粗	`#` 后加一个空格
列表错乱	嵌套全平级了	子项缩进 2~4 空格
列表断裂	多行补充说明后列表断开	补充段落缩进对齐
表格不显示	变成普通文本	确认 `\|` + `---` 分隔行、列数一致
代码高亮无效	代码块无色	围栏后写明语言
转义失败	`\*` 还生效	确认反斜杠紧贴符号无空格
图片不显示	只显示替代文字	检查路径 / URL、大小写、中文空格
引用断掉	引用中间断了	空行也加 `>`
公式不渲染	显示 $...$ 原文	确认平台支持、`$` 前后无多余空格
换平台排版变样	同一文件效果不同	只用通用 / GFM 语法，私有扩展加注释

22. 跨平台兼容性

优先用通用语法：标题、列表、粗斜体、引用、代码、链接、图片、分割线 —— 任何平台都支持，放心用；
谨慎用扩展语法：表格、删除线、任务列表、脚注、公式、Mermaid、Emoji、[TOC]—— 主流平台支持，个别老编辑器不支持；
标注扩展：文档可能被不同工具打开时，对扩展语法加注释说明；
一个文件一个主标题，层级不乱，方便自动目录和锚点。

第五部分：实战场景模板

直接复制改成自己的内容即可。

模板一：技术文档 / README

# 项目名

> 一句话介绍这个项目是做什么的。

## 功能特性

- 特性一
- 特性二

## 快速开始

### 环境要求

- Node.js >= 18

### 安装

```bash
npm install

API 文档

方法	参数	返回值	说明
`foo()`	`a, b`	`number`	求和


### 模板二：日报 / 周报

```markdown
# 工作周报（10.13 ~ 10.17）

## 本周完成

- [x] 需求评审
- [x] 首页改版开发
- [ ] 联调测试（进行中）

## 下周计划

1. 完成联调测试
2. 上线发布

## 风险

> ⚠️ 接口联调延迟，可能导致上线延期。

模板三：学习笔记

# 标题：数据库索引原理

## 核心结论

> 索引是数据库为加速查询建立的数据结构。

## 关键点

- **主键索引**：唯一且非空
- **复合索引**：最左前缀原则

## 示例

```sql
CREATE INDEX idx_name ON users(name);


---

## 附录：一页速查表

```markdown
# 标题1 ~ ###### 标题6
**粗体**  *斜体*  ***粗斜体***  ~~删除线~~  ==高亮==  `行内代码`

- 无序列表
1. 有序列表
- [ ] 任务    - [x] 已完成

> 引用
>> 嵌套引用

[链接](url "标题")
![图片](url)
[![图片](图片地址)](跳转地址)

| 表头 | 表头 |
| --- | --- |
| 内容 | 内容 |

---

```语言
代码块

$行内公式$ $块级公式$

:emoji: [^ 脚注]


---

> 🎉 **恭喜！** 掌握以上内容，你已经能应对 99% 的 Markdown 写作场景。
> 建议边看边在编辑器里亲手敲一遍，印象更深。✍️

来自随笔 10 月 13 日