Markdown 语法完全指南:从入门到进阶

Markdown 是一种用纯文本就能写出排版效果的标记语言,本文按"基础 → 进阶 → 扩展"的顺序介绍它的全部常用语法,文末附速查表。本文本身就是一份活的示例:每个语法点的"写法"用代码块展示,"效果"就是紧随其后的真实渲染结果。

一、标题

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

规则与建议:

• # 与标题文字之间必须有一个空格;
• 页面 H1 通常留给文章标题(Halo 主题会渲染文章标题),正文从 ## 开始;
• 不要跳级(如 ## 直接跳 ####),目录层级才清晰;
• 另有 Setext 写法(文字下一行加 === 或 ---),可读性差,不推荐。

二、段落与换行

这是一个段落。段落之间用一个空行分隔。

这是第二个段落。同一段落内连续敲多个空格,渲染后只算一个。

行尾敲两个空格  
或行尾放一个反斜杠\
都能实现"不分段、只换行"。

效果:

这是一个段落。段落之间用一个空行分隔。

这是第二个段落。同一段落内连续敲多个空格,渲染后只算一个。

行尾敲两个空格
或行尾放一个反斜杠
都能实现"不分段、只换行"。

记忆口诀:单个回车 = 同段;空行 = 分段;行尾两空格 / \ / <br> = 强制换行。

三、文字样式

*斜体*  _斜体_
**粗体**  __粗体__
***粗斜体***
~~删除线~~
`行内代码`

效果:斜体 / 粗体 / 粗斜体 / 删除线 / 行内代码

细节:

• * 与 _ 等价,中文排版推荐统一用 *(_ 紧贴中文时容易失效);
• 强调符号要贴紧文字,** 粗体 ** 这种内侧带空格的写法不生效;
• 行内代码里的 * _ < 等特殊字符不需要转义,是写 shell 命令和路径的好帮手。

四、分隔线

---
***
___

三个及以上的 -、*、_ 独占一行即可(三种等价)。注意:--- 若紧贴在上一行文字下面,会被解析成 Setext 二级标题——上一行记得留空行。

五、引用

> 这是一段引用。
> 引用可以有很多行。

> 引用里还能继续嵌套:
> > 二级引用
> > > 三级引用

> 引用里可以放**粗体**、`代码`、链接等行内元素,
> 也可以放列表:
>
> - 列表项一
> - 列表项二

效果:

这是一段引用。
引用可以有很多行。

引用里还能继续嵌套:

二级引用

三级引用

引用里可以放粗体、代码、链接等行内元素,
也可以放列表:

• 列表项一
• 列表项二

六、列表

1. 无序列表

- 减号
+ 加号
* 星号

三种符号等价,同一篇文档固定用一种。

2. 有序列表

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

即使数字写乱(全写 1.),渲染时也会按顺序自动修正——但请老实写,方便版本 diff。

3. 嵌套列表

- 水果
  - 苹果
    - 红富士
- 主食

效果:

• 水果
  • 苹果
    • 红富士
• 主食

层级靠缩进表达:子项比父项多缩进 2 个空格(或 1 个 Tab)。无序、有序可以互相嵌套。列表项内想再放段落/代码块,同样缩进对齐即可。

4. 任务列表(GFM)

- [x] 配好 S3 存储桶
- [x] 初始化仓库
- [ ] 配置 systemd 定时备份
- [ ] 演练一次恢复

效果:

• 配好 S3 存储桶
• 初始化仓库
• 配置 systemd 定时备份
• 演练一次恢复

七、代码

1. 行内代码

用反引号包裹:pip install restic,适合命令、文件名、字段名。

2. 围栏代码块(推荐)

```python
def hello(name: str) -> str:
    return f"Hello, {name}!"
```

首行标注语言可获得语法高亮。常用标识:bash python json yaml sql js ts java go c ini powershell text。

效果:

def hello(name: str) -> str:
    return f"Hello, {name}!"

3. 缩进式代码块

每行缩进 4 个空格也会被解析成代码块,但不支持高亮、还容易和列表嵌套混淆——统一用围栏式。

4. 如何展示"反引号本身"?

外层用四个及以上反引号包裹即可(本文的语法演示大量用了这招)。

八、链接

[行内链接](https://restic.readthedocs.io/)
[带提示的链接](https://restic.readthedocs.io/ "悬停显示的文字")
[引用式链接][restic]

[restic]: https://restic.readthedocs.io/ "定义放在文末或附近,适合多处复用"

<https://github.com/restic/restic>

效果:行内链接 / 带提示的链接 / 引用式链接 / https://github.com/restic/restic

补充:

• 链接文字里可以再套粗体或 行内代码;
• 裸链接(GFM)多数渲染器会自动识别成可点击链接,但显式写 <> 兼容性更好;
• 页内锚点跳转依赖渲染器生成的 id 规则,中文标题锚点兼容性差,尽量少用。

九、图片

![加载失败时显示的描述文字](https://example.com/cat.jpg "悬停提示")

• 语法 = 链接前面多一个 !;
• alt 描述务必认真写:图片挂了显示它,无障碍阅读和 SEO 都依赖它;
• 控制尺寸、圆角等需求没有原生语法,用 HTML:

<img src="https://example.com/cat.jpg" alt="宽 300 像素" width="300" />

十、表格(GFM)

| 语法 | 快捷键 | 备注 |
|:-----|:------:|-----:|
| 粗体 | Ctrl+B | 左对齐 |
| 斜体 | Ctrl+I | 居中 |
| 删除线 | 无 | 右对齐 |

效果:

要点:

• 第二行冒号的位置决定对齐::--- 左、:---: 中、---: 右,不带冒号默认左对齐;
• 单元格内可以用粗体、代码、链接;内容里的竖线要写成 \|;
• 表格前后记得留空行,否则不渲染;列数建议不超过 5 列(照顾手机)。

十一、转义字符

想让 Markdown 语法字符按原样显示,在前面加反斜杠 \:

十二、内嵌 HTML

Markdown 兼容 HTML,自己没有的功能用 HTML 补:

• 键盘按键:Ctrl + C + V
• 上下标:H₂O、10²⁴
• 高亮:黄色荧光笔效果
• 居中:
  这行用 HTML 居中
• 折叠面板(适合长日志、剧透):

<details>
<summary>点击展开:长输出示例</summary>

折叠区里可以继续写 Markdown(summary 与正文之间留空行)。

- 列表也能用
- `代码`也可以

</details>

效果:

⚠️ HTML 标签内部的 Markdown 语法不会被解析,两种写法不要在同一块里来回嵌套。另外站点渲染器通常有安全过滤,<script> 之类会被剥掉。

十三、扩展语法(视渲染器/主题/插件而定)

先分个类:CommonMark 核心(标题、段落、强调、引用、列表、代码块、链接、图片)+ GFM 扩展(表格、删除线、任务列表、自动链接)是主流渲染器的标配;下面这些则不一定支持,以你站点的实际渲染效果为准——正好可以用本文自查。

1. 脚注

Restic 使用 AES-256 加密[^1],按内容分块去重[^2]。

[^1]: Advanced Encryption Standard,高级加密标准。
[^2]: Content-Defined Chunking,内容定义分块。

支持时,[^1] 会渲染成上标数字,点击跳到文末注释;不支持时原样显示。

2. 高亮

==这句话被荧光笔标黄==

不支持时改用 HTML:<mark>高亮</mark>。

3. 上标 / 下标

H~2~O    2^10^ = 1024

兼容性一般,更稳的是 HTML:H<sub>2</sub>O、2<sup>10</sup>。

4. Emoji 短代码

:tada: :rocket: :bug: :warning:

GitHub 支持并渲染成 🎉 🚀 🐛 ⚠️;不支持时会原样显示冒号代码——最稳的做法是直接粘贴 emoji 字符:🎉 🚀 🐛 ⚠️

5. 数学公式(KaTeX / MathJax,需插件或主题内置)

行内公式 $E = mc^2$,行间公式:

$$
\int_{a}^{b} f(x)\,dx = F(b) - F(a)
$$

6. Mermaid 图表(需插件或主题内置)

```mermaid
graph LR
    A[写文章] --> B{是否发布}
    B -->|是| C[读者可见]
    B -->|否| D[存为草稿]
```

7. GitHub 风格告示块(较新渲染器支持)

> [!NOTE]
> 有用的补充说明。

> [!WARNING]
> 危险操作提醒。

8. 注释

<!-- 这段话渲染后不可见,适合给自己留备注 -->

十四、写作建议

1. 标题语义化:从 ## 开始、层级不跳级,目录才好看;
2. 代码块标语言:高亮 + 一键复制,体验天差地别;
3. 图片写 alt,链接文字说清去处,别满篇"点这里";
4. 列表嵌套 ≤ 3 层,表格 ≤ 5 列(照顾手机端);
5. 中文与英文、数字之间留一个空格,排版观感立刻上一个档次;
6. 长文先列大纲再填肉,Markdown 的结构感就是写作效率;
7. 常用工具:VS Code(内置预览)、Typora(所见即所得)、Obsidian(笔记 + 双链),以及 Halo 后台编辑器的 Markdown 快捷输入。

十五、速查表