这篇文章用来集中记录 Markdown 的常见格式。

以后写博客时，如果忘了某个格式怎么写，可以直接回到这里查。

说明：不同平台对 Markdown 的支持略有差异。这里以个人博客、GitHub 常见写法和 Hugo 常用 Markdown 为主。

1. 标题

Markdown 用 # 表示标题。
# 越多，标题级别越低。

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

实际效果：

一级标题示例

二级标题示例

三级标题示例

四级标题示例

五级标题示例

六级标题示例

2. 段落

普通文字直接写就是段落。

这是第一段。

这是第二段。

实际效果：

这是第一段。

这是第二段。

3. 换行

Markdown 里普通回车不一定会变成换行。
如果想在同一个段落里强制换行，可以在行尾加两个空格，或者直接空一行分成两个段落。

第一行后面有两个空格  
第二行会换行显示

实际效果：

第一行后面有两个空格
第二行会换行显示

4. 粗体、斜体、粗斜体

**粗体**
*斜体*
***粗斜体***

实际效果：

粗体

斜体

粗斜体

5. 删除线

~~这是一段被删除的文字~~

实际效果：

这是一段被删除的文字

6. 行内代码

用反引号包住一小段代码或命令。

使用 `hugo server` 启动本地预览。

实际效果：

使用 hugo server 启动本地预览。

7. 代码块

用三个反引号包住多行代码。
可以在开头标注语言，方便高亮。

```powershell
hugo server -D
```

实际效果：

hugo server -D

JavaScript 示例：

function hello(name) {
  return `Hello, ${name}`;
}

console.log(hello('Markdown'));

HTML 示例：

<article>
  <h1>标题</h1>
  <p>正文</p>
</article>

8. 引用

用 > 表示引用。

> 这是一段引用。

实际效果：

这是一段引用。

引用可以嵌套：

> 第一层引用
>
> > 第二层引用

实际效果：

第一层引用

第二层引用

9. 无序列表

可以用 -、* 或 + 写无序列表。建议统一使用 -。

- 第一项
- 第二项
- 第三项

实际效果：

• 第一项
• 第二项
• 第三项

10. 有序列表

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

实际效果：

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

数字不一定非要连续，Markdown 通常会自动整理：

1. 第一项
1. 第二项
1. 第三项

实际效果：

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

11. 嵌套列表

子列表通常缩进两个或四个空格。

- 写作
  - 选题
  - 草稿
  - 修改
- 发布
  - 提交
  - 构建
  - 上线

实际效果：

• 写作
  • 选题
  • 草稿
  • 修改
• 发布
  • 提交
  • 构建
  • 上线

12. 任务列表

任务列表常用于待办事项。

- [x] 已完成
- [ ] 未完成
- [ ] 以后再做

实际效果：

• 已完成
• 未完成
• 以后再做

13. 链接

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

实际效果：

Hugo 官方文档

也可以写自动链接：

<https://gohugo.io/>

实际效果：

https://gohugo.io/

14. 图片

图片写法和链接类似，只是在前面多一个 !。

![图片说明](../../og-default.svg)

实际效果：

图片说明文字很重要。图片加载失败时，它会作为替代文本显示。

15. 表格

| 名称 | 作用 | 备注 |
| --- | --- | --- |
| `#` | 标题 | 数量表示级别 |
| `**` | 粗体 | 常用于强调 |
| `` ` `` | 代码 | 行内代码 |

实际效果：

表格对齐

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| A | B | C |
| 100 | 200 | 300 |

实际效果：

16. 分隔线

可以用三个或更多 -、*、_ 表示分隔线。

---

实际效果：

17. 脚注

脚注适合补充说明，不打断正文阅读。

这里有一个脚注。[^note]

[^note]: 这是脚注内容。

实际效果：

这里有一个脚注。¹

18. 转义字符

如果想显示 Markdown 符号本身，可以在前面加反斜杠。

\*这不会变成斜体\*
\# 这不会变成标题

实际效果：

*这不会变成斜体*

# 这不会变成标题

常见需要转义的字符：

\ 反斜杠
` 反引号
* 星号
_ 下划线
{} 花括号
[] 方括号
() 圆括号
# 井号
+ 加号
- 减号
. 英文句点
! 感叹号
| 竖线

19. HTML

有些 Markdown 环境允许直接写 HTML。

<mark>高亮文字</mark>
<kbd>Ctrl</kbd> + <kbd>S</kbd>

不过这个博客当前的 Hugo 配置里，Goldmark 的 unsafe 是关闭的。
所以普通文章里不建议依赖 HTML 标签。能用 Markdown 写，就尽量用 Markdown。

20. 注释

Markdown 没有统一的注释语法。很多平台会使用 HTML 注释：

<!-- 这是一段注释 -->

但是否显示、是否保留，取决于平台配置。写博客时不建议把重要信息放进注释里。

21. 反引号里显示反引号

如果代码里本身有反引号，可以用更多反引号包起来。

`` `code` ``

实际效果：

`code`

22. 链接标题

链接可以带标题，鼠标悬停时部分浏览器会显示。

[Hugo](https://gohugo.io/ "Hugo 官方网站")

实际效果：

Hugo

23. 引用里的其他格式

引用里也可以包含列表、代码和强调。

> **提示**
>
> - 可以写列表
> - 可以写 `代码`

实际效果：

提示

• 可以写列表
• 可以写 代码

24. 列表里的代码块

列表里放代码块时，代码块需要缩进。

1. 第一步

   ```bash
   git status
   ```

2. 第二步

实际效果：

1. 第一步

   git status
   

2. 第二步

25. Front Matter

Hugo 文章最上面的元信息叫 front matter。
这个博客现在主要使用 TOML front matter。

+++
title = '文章标题'
date = '2026-04-15'
description = '文章摘要'
tags = ['Markdown', '写作']
+++

常见字段：

26. 标签和系列

这不是 Markdown 标准语法，而是这个博客的内容组织方式。

普通文章可以写：

tags = ['写作', '工具']

系列文章可以写：

series = ['Agent 学习']
series_order = 1

27. 常用写作模板

一篇普通文章大概可以这样写：

+++
title = '标题'
date = '2026-04-15'
description = '一句话摘要。'
tags = ['标签一', '标签二']
+++

开头先说明这篇文章想解决什么问题。

## 第一部分

写主要内容。

## 第二部分

继续展开。

## 小结

收回来，写结论。

28. 常见错误

列表和正文之间没有空行

有些时候列表前后需要空行，否则渲染可能不符合预期。

表格分隔行写错

表格第二行必须是 --- 这样的分隔行。

图片路径写错

在这个博客里，文章里的图片建议放在 static/posts/ 下，并使用适合站点路径的相对路径。

标题层级跳太快

建议按顺序使用标题：

h1 -> h2 -> h3

不要一上来就从 ## 跳到 #####。

29. 快速索引

30. 小结

Markdown 的重点不是复杂，而是让写作尽量接近纯文本。

对这个博客来说，最常用的格式其实只需要记住：

• 标题
• 段落
• 列表
• 引用
• 链接
• 图片
• 代码块
• 表格

其余格式可以需要时再查。