Markdown 完全速查手册：从基础语法到进阶技巧

为什么要学 Markdown

每次写技术文档、README、博客文章，都要在富文本编辑器里点来点去调格式？Markdown 能让你只用键盘就写出结构清晰的文档，写完直接转 HTML，在 GitHub、Notion、语雀、掘金等平台上开箱即用。

学一次，到处能用。

基础语法

标题

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

# 和标题文字之间必须有一个空格，否则部分解析器不识别。

段落与换行

Markdown 里直接按回车不会换行——这是最常见的新手困惑。

这是第一行
这是第二行（和上面在同一段落）

这是新段落（空一行才会分段）

强制换行的两种方法：

• 行尾加两个空格再回车
• 行尾加 \（部分平台支持）

强调

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体*** 或 ___粗斜体___
~~删除线~~

效果：斜体、粗体、粗斜体、删除线

列表

无序列表（-、*、+ 均可）：

- 苹果
- 香蕉
  - 大蕉（嵌套，缩进2个空格）
  - 小米蕉
- 橙子

有序列表：

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

有序列表的数字不影响最终渲染顺序，全写 1. 也会自动编号，但建议按序写便于阅读源码。

链接

[链接文字](https://toolshu.com)
[带标题的链接](https://toolshu.com "鼠标悬停显示的标题")

<!-- 引用式链接，适合文中多次引用同一URL -->
[toolshu][1]

[1]: https://toolshu.com

图片

![替代文字](https://example.com/image.png)
![替代文字](https://example.com/image.png "图片标题")

Markdown 原生不支持指定图片尺寸，如需控制大小需用 HTML：

<img src="https://example.com/image.png" width="300" alt="描述">

引用块

> 这是引用内容
> 可以多行
>
> 空行保留引用块

> 引用块可以嵌套
>> 二级引用
>>> 三级引用

代码

行内代码：用反引号包裹

执行 `npm install` 安装依赖

代码块：用三个反引号包裹，后面加语言名开启语法高亮

```javascript
const greeting = "Hello, World!";
console.log(greeting);
```

常用语言标识：javascript、python、java、bash、sql、json、css、html、go、rust

分割线

---
***
___

三种写法效果一样，推荐用 ---，视觉上最清晰。

进阶语法（GFM）

以下语法属于 GitHub Flavored Markdown（GFM），在 GitHub、GitLab、大多数主流平台均支持，但不在原始 Markdown 规范内。

表格

| 名称     | 类型   | 描述           |
|----------|--------|----------------|
| id       | int    | 用户唯一标识   |
| username | string | 用户名         |
| email    | string | 邮箱地址       |

对齐控制：

| 左对齐   | 居中对齐 | 右对齐   |
|:---------|:--------:|---------:|
| 内容     | 内容     | 内容     |

表格小技巧：列宽不用对齐，解析器会自动处理，但对齐了源码更易读。

任务列表

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

GitHub、Notion、语雀等平台会渲染成可勾选的复选框。

脚注

这里有个需要说明的内容[^1]。

[^1]: 这是脚注内容，会显示在文章底部。

自动链接

直接写 URL 会自动变成链接：https://toolshu.com
或者用尖括号：<https://toolshu.com>

代码块内的转义

如果代码块本身要包含三个反引号，外层用四个反引号包裹：

````
```这里是三个反引号，不会被解析```
````

容易踩的坑

1. 列表后接代码块需要空行

- 列表项

    代码块（用4个空格缩进，或空行后用围栏式）

2. 标题前需要空行

上一段文字

## 标题（前面空一行才能正确解析）

3. 同一段落内加粗不能跨行

**这是粗体
换行后不生效**   ← 部分解析器会失效

4. 表格单元格里不能直接换行

表格单元格里需要换行时，用 <br> 标签：

| 列1              | 列2   |
|------------------|-------|
| 第一行<br>第二行 | 内容  |

各平台差异速览

写完 Markdown 想直接看 HTML 渲染效果，或者手上有一段 HTML 想转成 Markdown 来编辑，可以用 Markdown/HTML 互转工具，粘进去实时预览，省去搭本地环境的麻烦。