# Markdown 基础与扩展语法 标题、段落、列表、表格、引用与脚注，集中查阅常用排版语法。 本篇属于 [Markdown 语法手册](/collections/markdown/)。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。 ## 基础排版：标题、段落与文字 ### 标题与段落 文章标题由 front matter 的 `title` 提供，正文通常从二级标题开始，避免重复一级标题。 ```markdown ## 一次出发 ### 路上的风景 这是第一段。连续的普通换行通常仍属于同一段。 空一行，开始第二段。 ``` #### 一次出发 这是第一段。连续的普通换行通常仍属于同一段。 空一行，开始第二段。 上方为了保持本页目录层级，将实际演示标题降为四级。标题符号后必须留一个空格；段落之间留一个空行。 ### 换行：另起一行，还是另起一段 普通换行主要用于整理源码。想在同一段内明确换行，可以在行尾写反斜杠；想另起一段，就空一行。 ```markdown 第一行，先记下天气。\ 第二行，再写下此刻的心情。 这一段换了一个话题。 ``` 第一行，先记下天气。\ 第二行，再写下此刻的心情。 这一段换了一个话题。 行尾两个空格也能产生硬换行，但编辑器可能自动清理它们。对于需要稳定保持行数的短诗，反斜杠更容易在源码里识别。不要用连续空格做段落缩进，网页通常会折叠这些空格。 ### 强调与行内代码 ```markdown **值得记住**，*轻声提醒*，以及 `hugo server`。 ``` **值得记住**，*轻声提醒*，以及 `hugo server`。 中文字体的斜体显示由设备字体决定。文件名、命令与配置键适合行内代码，避免整段加粗。 ### 分隔线与转义 ```markdown 上半部分。 --- 下半部分。\*这是星号，不是强调\*。 ``` 上半部分。 --- 下半部分。\*这是星号，不是强调\*。 分隔线前后留空行，避免与标题下划线语法混淆。反斜杠可以转义 Markdown 标点；但 Hugo 短代码需要专用注释转义，见[短代码入门与提示框](/wiki/fixit-shortcodes/)。 ## 列表与引用 ### 有序与无序列表 ```markdown - 收集想法 - 整理材料 - 记录来源 - 保存图片 1. 写下初稿 2. 本地预览 3. 检查链接 ``` - 收集想法 - 整理材料 - 记录来源 - 保存图片 1. 写下初稿 2. 本地预览 3. 检查链接 子列表需要缩进。复杂列表内放代码块时，缩进应与该列表项正文对齐。 ### 列表项里放说明和代码 一项操作可能不止一句话。把后续段落和代码块缩进到该项正文的位置，就能保留步骤的归属关系。 ````markdown 1. 新建文章。 文件名采用简短英文，中文标题写在文章头部。 ```sh ./scripts/hugo.sh new content posts/weekend-notes.md ``` 2. 写一个能概括内容的开头。 - 说明遇到了什么问题。 - 说明读者能从本文得到什么。 ```` 1. 新建文章。 文件名采用简短英文，中文标题写在文章头部。 ```sh ./scripts/hugo.sh new content posts/weekend-notes.md ``` 2. 写一个能概括内容的开头。 - 说明遇到了什么问题。 - 说明读者能从本文得到什么。 这里列表项从 `1. ` 后的第四列开始，因此后续内容缩进三个空格。不同标记宽度可能需要不同缩进，不要机械地给所有嵌套内容加相同空格。 ### 引用 ```markdown > 沧浪之水清兮，可以濯吾缨 > > 沧浪之水浊兮，可以濯吾足。 ``` > 沧浪之水清兮，可以濯吾缨 > > 沧浪之水浊兮，可以濯吾足。 每段引用以 `>` 开始。空引用行可以把引用拆成两个段落。 ### 引用中也能包含结构 ```markdown > **本周记录** > > - 完成一篇技术笔记。 > - 修正一处模糊的解释。 > > 写作不是一次完成，而是在回看时不断变清楚。 ``` > **本周记录** > > - 完成一篇技术笔记。 > - 修正一处模糊的解释。 > > 写作不是一次完成，而是在回看时不断变清楚。 引用里的空行也写一个 `>`，这样段落和列表都明确属于引用。只有需要表达“引用中的引用”时，再使用 `>>`。 ## 表格与任务清单 ### 表格与对齐 ```markdown | 内容 | 用途 | 数量 | | :--- | :---: | ---: | | 文章 | 记录 | 5 | | 合集 | 归档 | 1 | ``` | 内容 | 用途 | 数量 | | :--- | :---: | ---: | | 文章 | 记录 | 5 | | 合集 | 归档 | 1 | 分隔行中的冒号决定左、中、右对齐。单元格中需要竖线时写 `\|`。表格适合短内容，长段落更适合列表。 ### 表格中的链接、强调与竖线 ```markdown | 写法 | 用途 | 示例 | | :--- | :--- | :--- | | **加粗** | 提醒读者关注 | **先检查草稿状态** | | 链接 | 指向解释页面 | [合集](/collections/markdown/) | | 竖线 | 表示“或”等关系 | A \| B | | 行内代码 | 配置项或文件名 | `hugo.toml` | ``` | 写法 | 用途 | 示例 | | :--- | :--- | :--- | | **加粗** | 提醒读者关注 | **先检查草稿状态** | | 链接 | 指向解释页面 | [合集](/collections/markdown/) | | 竖线 | 表示“或”等关系 | A \| B | | 行内代码 | 配置项或文件名 | `hugo.toml` | 表格中的竖线需要转义，否则会被当作新列。复杂代码、多段说明或大幅图片不适合挤在单元格里；可以在表格中概括，再在表格外解释。 ### 任务清单 ```markdown - [x] 整理目录 - [x] 完成初稿 - [ ] 校对后发布 ``` - [x] 整理目录 - [x] 完成初稿 - [ ] 校对后发布 `[ ]` 内是一个半角空格。这里的复选框是文章内容展示，不会将点击状态保存到 Markdown。 ### 有层次的发布清单 ```markdown - [x] 完成正文 - [x] 补齐来源 - [x] 给示例添加说明 - [ ] 完成验收 - [x] 桌面预览 - [ ] 手机预览 - [ ] 检查深色模式 ``` - [x] 完成正文 - [x] 补齐来源 - [x] 给示例添加说明 - [ ] 完成验收 - [x] 桌面预览 - [ ] 手机预览 - [ ] 检查深色模式 父项不会自动根据子项完成情况更新，需要在 Markdown 源文件中手动维护。清单写成可以验证的动作，比“继续优化”“做好检查”更容易执行。 ## 链接、脚注与术语 ### 把链接定义放到段落后面 同一个目标在一篇文章中出现多次时，引用式链接能让正文更清楚。 ```markdown 基础语法见[第一篇][basics]，所有文章收录在[写作合集][collection]。 读完后，也可以回到[第一篇][basics]做一次练习。 [basics]: /wiki/markdown-basics/ "Markdown 基础语法" [collection]: /collections/markdown/ "完整合集" ``` 基础语法见[第一篇][basics]，所有文章收录在[写作合集][collection]。 读完后，也可以回到[第一篇][basics]做一次练习。 [basics]: /wiki/markdown-basics/ "Markdown 基础语法" [collection]: /collections/markdown/ "完整合集" 定义可以放在文末，不会单独显示。标识建议用简短英文，避免修改可见标题时还要同时修改所有引用。 ### 脚注 ```markdown 先写正文，再补充背景。[^note] [^note]: 脚注可用于来源、术语或不影响主线的解释。 ``` 先写正文，再补充背景。[^note] [^note]: 脚注可用于来源、术语或不影响主线的解释。 引用和定义使用相同标识，渲染器会生成编号、文末脚注与返回链接。 ### 脚注里的第二段 ```markdown 本次只记录已经验证的行为。[^scope] [^scope]: 验证范围是当前固定版本。 不同版本或不同配置可能产生不同结果，升级后需要重新检查。 ``` 本次只记录已经验证的行为。[^scope] [^scope]: 验证范围是当前固定版本。 不同版本或不同配置可能产生不同结果，升级后需要重新检查。 脚注后续段落缩进四个空格。不要把重要步骤藏在脚注中；脚注更适合补充范围、来源或背景。 ### 定义列表 ```markdown Front matter : 位于文件开头的元数据。 Page bundle : 将文章正文和图片放在同一目录的内容组织方式。 ``` Front matter : 位于文件开头的元数据。 Page bundle : 将文章正文和图片放在同一目录的内容组织方式。 ## 文字扩展 ### 删除、高亮与上下标 ```markdown ~~旧方案~~，==重点==，H~2~O，x^2^。 ``` ~~旧方案~~，==重点==，H~2~O，x^2^。 这些扩展由固定版本的 `markup.goldmark.extensions.extras` 开启。上下标内容不要包含未转义空格；复杂表达式使用[数学公式章节](/wiki/math-and-diagrams/)。 ### 下划线与组合强调 ```markdown ++新增内容++，**加粗文字**，*斜体文字*，***加粗且斜体***。 ``` ++新增内容++，**加粗文字**，*斜体文字*，***加粗且斜体***。 `++...++` 是本站启用的插入文本扩展，通常显示为下划线，不是所有 Markdown 编辑器都支持。下划线容易让人误认为链接，因此正文强调优先使用加粗。 ### Emoji ```markdown :books: 整理知识，:wrench: 记录折腾，:pencil: 随手写下想法。 ``` :books: 整理知识，:wrench: 记录折腾，:pencil: 随手写下想法。 本站开启了 `enableEmoji`，支持 Emoji 简码；也可以直接输入 📚、🔧、✏️。字符 Emoji 的外观由系统决定，不能保证所有设备完全相同。 ## 链接、图片与代码入门 ### 普通链接与定位标记 ```markdown [阅读写作流程](/wiki/writing-workflow/ "文章模板与写作发布流程") [回到本节](#链接图片与代码入门) ``` [阅读写作流程](/wiki/writing-workflow/ "文章模板与写作发布流程") · [回到本节](#链接图片与代码入门) 链接文字说明目的，括号里填写地址，可选的引号内容是悬停说明。页内链接使用标题生成的锚点；标题修改后应重新检查对应锚点。不要把本机磁盘路径当成站内地址。 ### 图片与替代文本 ```markdown ![本站图标](/favicon.svg "本站图标") ``` ![本站图标](/favicon.svg "本站图标") 方括号中是替代文本，用来描述图片；引号中的 title 是附加说明。本站开启的图片灯箱对带 title 的图片生效。较复杂的图文排版与资源路径见[富文本写作](/wiki/images-and-links/)。 ### 围栏代码块 ````markdown ```sh hugo version ``` ```` ```sh hugo version ``` 三个反引号开始和结束代码块，语言名控制高亮。要演示包含三个反引号的源码，外层使用四个反引号。代码高亮、行号、标题与复制按钮的详细写法统一放在[富文本写作](/wiki/images-and-links/)。 ### 注释与少量 HTML ```markdown 可见的文字。 按 Esc 退出。 ``` 可见的文字。 按 Esc 退出。 HTML 注释不显示为正文，但不要用它保存密码或其他秘密。少量 HTML 可补充 Markdown 无法表达的内容；是否允许渲染取决于站点配置，不同平台可能过滤这些标签。 ## 扩展能力与专题入口 ### 警示块 ```markdown > [!NOTE] > 保存后先本地预览，再检查图片和链接。 ``` > [!NOTE] > 保存后先本地预览，再检查图片和链接。 警示块适合短提示。复杂提示框、折叠、标签页与文件树见[Shortcodes 与组件](/wiki/fixit-shortcodes/)，避免把所有组件说明都挤进基础语法文章。 ### Markdown 属性 本站支持给部分 Markdown 块附加属性。写法是在元素后面紧接一行花括号；属性支持范围由渲染器与主题共同决定。 ```markdown > 一段居中展示的短句。 {.blockquote-center} ``` > 一段居中展示的短句。 {.blockquote-center} 这里的 `.blockquote-center` 是主题提供的样式类，不是通用 Markdown 语法。不要任意添加未知类名并期待它自动生效。 ### 公式与图表 简单行内公式可以写作 `$a^2+b^2=c^2$`，效果为 $a^2+b^2=c^2$。公式需要本站的数学渲染配置支持；其他编辑器可能直接显示源码。 多行公式、Mermaid、ECharts 和 Markmap 的可复制示例统一见[数学公式与可视化图表](/wiki/math-and-diagrams/)。 ## 标题层级与写作检查 ### 如何组织长文 | 层级 | 写法 | 本文用途 | | --- | --- | --- | | 一级 H1 | `# 标题` | 由文章 front matter 的 `title` 生成，正文无需重复 | | 二级 H2 | `## 标题` | 基础排版、列表与引用等大类 | | 三级 H3 | `### 标题` | 一项具体语法及其源码、效果、说明 | | 四级 H4 | `#### 标题` | 必要时继续拆分，不用于单纯缩小字号 | 当前目录默认收录 H2–H3，四级及更深标题仍在正文中正常显示。尽量按 H2 → H3 → H4 逐层展开，不要为了视觉大小跳级。多数写作手册使用 H2、H3 就足够；短小内容直接写段落，不必每一句都加标题。 ### 发布前检查 - 源码与实际效果是否一致，示例能否直接复制。 - 标题是否形成清晰的大类与小节，而不是全部平铺。 - 列表、代码围栏、引用与表格前后是否有必要的空行。 - 内部链接和标题锚点是否仍然有效。 - 扩展语法是否说明本站依赖，避免误认为所有 Markdown 平台都支持。 参考：[官方基础语法](https://fixit.lruihao.cn/zh-cn/docs/content-management/markdown-syntax/basics/)与[官方扩展语法](https://fixit.lruihao.cn/zh-cn/docs/content-management/markdown-syntax/extended/)。本文按本站实际配置整理常用内容；图片、短代码和图表的进阶用法继续维护在合集对应专题中。 --- > 作者: [yuehei](/authors/yuehei/) > URL: https://33.ax/wiki/markdown-basics/