Markdown 基础与扩展语法

标题、段落、列表、表格、引用与脚注，集中查阅常用排版语法。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

基础排版：标题、段落与文字

标题与段落

文章标题由 front matter 的 title 提供，正文通常从二级标题开始，避免重复一级标题。

1
2
3
4
5
6

## 一次出发
### 路上的风景

这是第一段。连续的普通换行通常仍属于同一段。

空一行，开始第二段。

一次出发

这是第一段。连续的普通换行通常仍属于同一段。

空一行，开始第二段。

上方为了保持本页目录层级，将实际演示标题降为四级。标题符号后必须留一个空格；段落之间留一个空行。

换行：另起一行，还是另起一段

普通换行主要用于整理源码。想在同一段内明确换行，可以在行尾写反斜杠；想另起一段，就空一行。

1
2
3
4

第一行，先记下天气。\
第二行，再写下此刻的心情。

这一段换了一个话题。

第一行，先记下天气。
第二行，再写下此刻的心情。

这一段换了一个话题。

行尾两个空格也能产生硬换行，但编辑器可能自动清理它们。对于需要稳定保持行数的短诗，反斜杠更容易在源码里识别。不要用连续空格做段落缩进，网页通常会折叠这些空格。

强调与行内代码

1

**值得记住**，*轻声提醒*，以及 `hugo server`。

值得记住，轻声提醒，以及 hugo server。

中文字体的斜体显示由设备字体决定。文件名、命令与配置键适合行内代码，避免整段加粗。

分隔线与转义

1
2
3
4
5

上半部分。

---

下半部分。\*这是星号，不是强调\*。

上半部分。

下半部分。*这是星号，不是强调*。

分隔线前后留空行，避免与标题下划线语法混淆。反斜杠可以转义 Markdown 标点；但 Hugo 短代码需要专用注释转义，见短代码入门与提示框。

列表与引用

有序与无序列表

1
2
3
4
5
6
7
8

- 收集想法
- 整理材料
  - 记录来源
  - 保存图片

1. 写下初稿
2. 本地预览
3. 检查链接

• 收集想法
• 整理材料
  • 记录来源
  • 保存图片

1. 写下初稿
2. 本地预览
3. 检查链接

子列表需要缩进。复杂列表内放代码块时，缩进应与该列表项正文对齐。

列表项里放说明和代码

一项操作可能不止一句话。把后续段落和代码块缩进到该项正文的位置，就能保留步骤的归属关系。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

1. 新建文章。

   文件名采用简短英文，中文标题写在文章头部。

   ```sh
   ./scripts/hugo.sh new content posts/weekend-notes.md
   ```

2. 写一个能概括内容的开头。

   - 说明遇到了什么问题。
   - 说明读者能从本文得到什么。

1. 新建文章。

   文件名采用简短英文，中文标题写在文章头部。

   1	./scripts/hugo.sh new content posts/weekend-notes.md

2. 写一个能概括内容的开头。

   • 说明遇到了什么问题。
   • 说明读者能从本文得到什么。

这里列表项从 1. 后的第四列开始，因此后续内容缩进三个空格。不同标记宽度可能需要不同缩进，不要机械地给所有嵌套内容加相同空格。

引用

1
2
3

> 沧浪之水清兮，可以濯吾缨
>
> 沧浪之水浊兮，可以濯吾足。

沧浪之水清兮，可以濯吾缨

沧浪之水浊兮，可以濯吾足。

每段引用以 > 开始。空引用行可以把引用拆成两个段落。

引用中也能包含结构

1
2
3
4
5
6

> **本周记录**
>
> - 完成一篇技术笔记。
> - 修正一处模糊的解释。
>
> 写作不是一次完成，而是在回看时不断变清楚。

本周记录

• 完成一篇技术笔记。
• 修正一处模糊的解释。

写作不是一次完成，而是在回看时不断变清楚。

引用里的空行也写一个 >，这样段落和列表都明确属于引用。只有需要表达“引用中的引用”时，再使用 >>。

表格与任务清单

表格与对齐

1
2
3
4

| 内容 | 用途 | 数量 |
| :--- | :---: | ---: |
| 文章 | 记录 | 5 |
| 合集 | 归档 | 1 |

分隔行中的冒号决定左、中、右对齐。单元格中需要竖线时写 \|。表格适合短内容，长段落更适合列表。

表格中的链接、强调与竖线

1
2
3
4
5
6

| 写法 | 用途 | 示例 |
| :--- | :--- | :--- |
| **加粗** | 提醒读者关注 | **先检查草稿状态** |
| 链接 | 指向解释页面 | [合集](/collections/markdown/) |
| 竖线 | 表示“或”等关系 | A \| B |
| 行内代码 | 配置项或文件名 | `hugo.toml` |

表格中的竖线需要转义，否则会被当作新列。复杂代码、多段说明或大幅图片不适合挤在单元格里；可以在表格中概括，再在表格外解释。

任务清单

1
2
3

- [x] 整理目录
- [x] 完成初稿
- [ ] 校对后发布

• 整理目录
• 完成初稿
• 校对后发布

[ ] 内是一个半角空格。这里的复选框是文章内容展示，不会将点击状态保存到 Markdown。

有层次的发布清单

1
2
3
4
5
6
7

- [x] 完成正文
  - [x] 补齐来源
  - [x] 给示例添加说明
- [ ] 完成验收
  - [x] 桌面预览
  - [ ] 手机预览
  - [ ] 检查深色模式

• 完成正文
  • 补齐来源
  • 给示例添加说明
• 完成验收
  • 桌面预览
  • 手机预览
  • 检查深色模式

父项不会自动根据子项完成情况更新，需要在 Markdown 源文件中手动维护。清单写成可以验证的动作，比“继续优化”“做好检查”更容易执行。

链接、脚注与术语

把链接定义放到段落后面

同一个目标在一篇文章中出现多次时，引用式链接能让正文更清楚。

1
2
3
4
5

基础语法见[第一篇][basics]，所有文章收录在[写作合集][collection]。
读完后，也可以回到[第一篇][basics]做一次练习。

[basics]: /wiki/markdown-basics/ "Markdown 基础语法"
[collection]: /collections/markdown/ "完整合集"

基础语法见第一篇，所有文章收录在写作合集。 读完后，也可以回到第一篇做一次练习。

定义可以放在文末，不会单独显示。标识建议用简短英文，避免修改可见标题时还要同时修改所有引用。

脚注

1
2
3

先写正文，再补充背景。[^note]

[^note]: 脚注可用于来源、术语或不影响主线的解释。

先写正文，再补充背景。¹

引用和定义使用相同标识，渲染器会生成编号、文末脚注与返回链接。

脚注里的第二段

1
2
3
4
5

本次只记录已经验证的行为。[^scope]

[^scope]: 验证范围是当前固定版本。

    不同版本或不同配置可能产生不同结果，升级后需要重新检查。

本次只记录已经验证的行为。²

脚注后续段落缩进四个空格。不要把重要步骤藏在脚注中；脚注更适合补充范围、来源或背景。

定义列表

1
2
3
4
5

Front matter
: 位于文件开头的元数据。

Page bundle
: 将文章正文和图片放在同一目录的内容组织方式。

Front matter

位于文件开头的元数据。

Page bundle

将文章正文和图片放在同一目录的内容组织方式。

文字扩展

删除、高亮与上下标

1

~~旧方案~~，==重点==，H~2~O，x^2^。

旧方案，重点，H₂O，x²。

这些扩展由固定版本的 markup.goldmark.extensions.extras 开启。上下标内容不要包含未转义空格；复杂表达式使用数学公式章节。

下划线与组合强调

1

++新增内容++，**加粗文字**，*斜体文字*，***加粗且斜体***。

新增内容，加粗文字，斜体文字，加粗且斜体。

++...++ 是本站启用的插入文本扩展，通常显示为下划线，不是所有 Markdown 编辑器都支持。下划线容易让人误认为链接，因此正文强调优先使用加粗。

Emoji

1

:books: 整理知识，:wrench: 记录折腾，:pencil: 随手写下想法。

📚 整理知识，🔧 记录折腾，📝 随手写下想法。

本站开启了 enableEmoji，支持 Emoji 简码；也可以直接输入 📚、🔧、✏️。字符 Emoji 的外观由系统决定，不能保证所有设备完全相同。

链接、图片与代码入门

普通链接与定位标记

1
2
3

[阅读写作流程](/wiki/writing-workflow/ "文章模板与写作发布流程")

[回到本节](#链接图片与代码入门)

阅读写作流程 · 回到本节

链接文字说明目的，括号里填写地址，可选的引号内容是悬停说明。页内链接使用标题生成的锚点；标题修改后应重新检查对应锚点。不要把本机磁盘路径当成站内地址。

图片与替代文本

1

![本站图标](/favicon.svg "本站图标")

方括号中是替代文本，用来描述图片；引号中的 title 是附加说明。本站开启的图片灯箱对带 title 的图片生效。较复杂的图文排版与资源路径见富文本写作。

围栏代码块

1
2
3

```sh
hugo version
```

1

hugo version

三个反引号开始和结束代码块，语言名控制高亮。要演示包含三个反引号的源码，外层使用四个反引号。代码高亮、行号、标题与复制按钮的详细写法统一放在富文本写作。

注释与少量 HTML

1
2
3

可见的文字。
<!-- 编辑备注：这段说明不显示在正文中。 -->
按 <kbd>Esc</kbd> 退出。

可见的文字。

按 Esc 退出。

HTML 注释不显示为正文，但不要用它保存密码或其他秘密。少量 HTML 可补充 Markdown 无法表达的内容；是否允许渲染取决于站点配置，不同平台可能过滤这些标签。

扩展能力与专题入口

警示块

1
2

> [!NOTE]
> 保存后先本地预览，再检查图片和链接。

警示块适合短提示。复杂提示框、折叠、标签页与文件树见Shortcodes 与组件，避免把所有组件说明都挤进基础语法文章。

Markdown 属性

本站支持给部分 Markdown 块附加属性。写法是在元素后面紧接一行花括号；属性支持范围由渲染器与主题共同决定。

1
2

> 一段居中展示的短句。
{.blockquote-center}

一段居中展示的短句。

这里的 .blockquote-center 是主题提供的样式类，不是通用 Markdown 语法。不要任意添加未知类名并期待它自动生效。

公式与图表

简单行内公式可以写作 $a^2+b^2=c^2$，效果为 $a^2+b^2=c^2$。公式需要本站的数学渲染配置支持；其他编辑器可能直接显示源码。

多行公式、Mermaid、ECharts 和 Markmap 的可复制示例统一见数学公式与可视化图表。

标题层级与写作检查

如何组织长文

当前目录默认收录 H2–H3，四级及更深标题仍在正文中正常显示。尽量按 H2 → H3 → H4 逐层展开，不要为了视觉大小跳级。多数写作手册使用 H2、H3 就足够；短小内容直接写段落，不必每一句都加标题。

发布前检查

• 源码与实际效果是否一致，示例能否直接复制。
• 标题是否形成清晰的大类与小节，而不是全部平铺。
• 列表、代码围栏、引用与表格前后是否有必要的空行。
• 内部链接和标题锚点是否仍然有效。
• 扩展语法是否说明本站依赖，避免误认为所有 Markdown 平台都支持。

参考：官方基础语法与官方扩展语法。本文按本站实际配置整理常用内容；图片、短代码和图表的进阶用法继续维护在合集对应专题中。