平时无论是写博客还是记笔记，Markdown 都是我的主力标记语言。它的语法简洁高效，能让人专注于内容本身。但时间一长，总有一些不常用的语法会忘记，比如表格的对齐、脚注的格式等等。

每次都去重新搜索感觉效率太低了，干脆自己整理一份核心语法清单，并附上渲染效果，当作速查备忘录。以后忘了就翻一下，特此记录。

1. 基础文本格式化

这部分是最常用、最基础的语法，用于控制文本的层级和样式。

1.1 标题 (Headings)

使用 # 号表示标题，一个 # 是一级标题，两个 ## 是二级，最多支持到六级。

语法示例：

# 一级标题
## 二级标题
### 三级标题

渲染效果：

一级标题

二级标题

三级标题

1.2 文本强调 (Emphasis)

  • 斜体 (Italic): 使用一对 * 或 _ 包裹文本。
  • 粗体 (Bold): 使用两对 * 或 _ 包裹文本。
  • 粗斜体 (Bold & Italic): 使用三对 * 或 _ 包裹文本。
  • 删除线 (Strikethrough): 使用两对 ~ 包裹文本。

语法示例：

*这是斜体*
_这也是斜体_

**这是粗体**
__这也是粗体__

***这是粗斜体***

~~这段文本将被标记为删除~~

渲染效果：

这是斜体 这也是斜体

这是粗体 这也是粗体

这是粗斜体

这段文本将被标记为删除

1.3 列表 (Lists)

  • 无序列表: 使用 -、* 或 + 开头，后跟一个空格。
  • 有序列表: 使用 数字. 开头，后跟一个空格。
  • 任务列表: 在列表项后添加 [ ] (未完成) 或 [x] (已完成)。

语法示例：

- 无序列表项 A
- 无序列表项 B

1. 有序列表项 1
2. 有序列表项 2

- [x] 已完成的任务
- [ ] 待办的任务

渲染效果：

  • 无序列表项 A
  • 无序列表项 B
  1. 有序列表项 1
  2. 有序列表项 2
  • 已完成的任务
  • 待办的任务

2. 内容嵌入与引用

用于在文章中插入链接、图片、代码等外部或特殊内容。

语法格式: ``

语法示例：

[点击访问 Google](https://www.google.com)

渲染效果：

点击访问 Google

提示 如果想在新标签页中打开链接，需要使用 HTML 的 <a> 标签实现，或者依赖主题的配置。Markdown 原生语法不支持此功能。

2.2 图片 (Images)

语法格式: ![图片替代文字(alt text)](图片地址)

alt text 在图片无法加载时显示，也有助于 SEO。

语法示例：

![Hugo Logo](https://upload.wikimedia.org/wikipedia/commons/a/af/Logo_of_Hugo_the_static_website_generator.svg)

渲染效果：

Hugo Logo

2.3 代码 (Code)

2.3.1 行内代码 (Inline Code)

使用一对反引号 ` 包裹代码片段。

语法示例：

在 JavaScript 中，可以使用 `console.log()` 来打印日志。

渲染效果：

在 JavaScript 中，可以使用 console.log() 来打印日志。

2.3.2 代码块 (Code Block)

使用三对反引号 包裹多行代码，并可在第一组后添加语言标识符以实现语法高亮。

语法示例：

```python
def hello_world():
    print("Hello, World!")

hello_world()
```

提示 为了在文档中展示“如何书写一个代码块”，我在外层使用了四个反引号(````)来包裹包含三个反引号的语法示例，这样可以避免解析错误。

渲染效果：

def hello_world():
    print("Hello, World!")

hello_world()

2.4 引用 (Blockquotes)

在段落前添加 > 符号。可以嵌套使用 >>。

语法示例：

> 这是一个引用块。
>
> 它可以包含多个段落。
> > 这是一个嵌套的引用。

渲染效果：

这是一个引用块。

它可以包含多个段落。

这是一个嵌套的引用。

3. 结构化数据

用于展示表格、分隔线等结构化内容。

3.1 表格 (Tables)

使用 | 分隔单元格，使用 - 分隔表头和表体。通过在分隔线中使用 : 来控制列的对齐方式。

注意 表格的定义部分必须与其前面的段落之间保留一个空行，否则可能无法正确渲染。

语法示例：

| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |

渲染效果：

左对齐 居中对齐 右对齐
Cell 1 Cell 2 Cell 3
Cell 4 Cell 5 Cell 6

3.2 水平分割线 (Horizontal Rules)

使用三个或更多的 *、- 或 _ 来创建一条水平分割线。

语法示例：

---
***
___

渲染效果：

4. 高级与特殊语法

这部分语法在特定场景下非常有用。

4.1 脚注 (Footnotes)

语法格式: 在需要添加脚注的文本后添加 [^标识符]，然后在文末通过 [^标识符]: 脚注内容 来定义。

语法示例：

Hugo 是一个基于 Go 语言开发的静态站点生成器[^1]。

[^1]: 更多信息请访问 Hugo 官网。

渲染效果：

Hugo 是一个基于 Go 语言开发的静态站点生成器1。

提示：脚注的定义内容通常会被渲染器统一收集并展示在页面的最底部。

4.2 转义字符 (Escaping)

如果你想在文本中显示 Markdown 的特殊语法符号（如 *, #, _），可以在符号前添加反斜杠 \ 进行转义。

语法示例：

\*这句话不会变成斜体\*
\# 这不会被渲染成一级标题

渲染效果：

*这句话不会变成斜体* # 这不会被渲染成一级标题

将标准的 URL 或邮箱地址用 < 和 > 包裹，Markdown 会自动将其转换为可点击的链接。

语法示例：

<https://gohugo.io>
<contact@example.com>

渲染效果：

https://gohugo.io contact@example.com

5. 常见问题与注意事项

在实践中，有几个点很容易混淆或出错，这里单独拎出来备忘一下。

  1. 行内代码 vs 代码块：

    • (单反引号) 用于包裹单个词或短语，比如函数名 printf() 或文件名 config.toml。
    • (三反引号) 用于包裹多行代码片段，可以指定语言实现语法高亮。

  2. 列表的缩进与嵌套：

    • 在父列表项下，通过缩进（通常是 2 个或 4 个空格）来创建子列表。不正确的缩进会导致列表渲染中断或格式错乱。

  3. 表格前的空行：

    • 这个坑我踩过好几次。一定要记住，表格的 | a | b | 定义之前必须有一个完整的空行，否则解析器可能无法识别它是一个表格。

好了，以上就是我整理的核心语法备忘。以后应该能省下不少查资料的时间了。

推荐阅读Basic writing and formatting syntax

  1. 更多信息请访问 Hugo 官网。 ↩︎