Markdown 基本语法
XOlDKING
发布于 2023/02/02
目录
系列 - Markdown 语法
本文介绍了最基本的 Markdown 语法规则、示例及其渲染生成的 HTML 样式，展示了在本博客 Hugo + FixIt 主题下的呈现效果。
信息
Hugo 是最受欢迎的开源静态网站生成器之一，号称是世界上最快的网站构建框架。
本博客目前使用 FixIt 主题，其 示例网站中提供了详尽的 中文文档。
从 0.60 版本之后，Hugo 采用 Goldmark 作为其默认 Markdown 语法渲染器（详情见 Configure markup in Hugo.）。 Goldmark 渲染速度快，配置灵活且遵循 CommonMark 标准。
引用
Markdown 由 John Gruber 于 2004 年与 Aaron Swartz 合作开发。
推荐参考 John Gruber’s Markdown Syntax 了解学习 Markdown 语法。
本文仅出于笔者个人学习、使用、查阅目的，简要列出笔者常用的 Markdown 语法，仅供参考。
标题
语法：
#空格标题内容
说明：
#个数对应标题级数
信息
Markdown 还支持其他 标题 样式，这里笔者选用了最简便的写法。
|
|
|
|
呈现的效果：
二级标题
三级标题
四级标题
五级标题
六级标题
注意
标题前的数字编号为本站设置的 CSS 样式。不同 Markdown 编辑器因其设置不同，可能将相同 Markdown 文本渲染成不同的效果。
强调
斜体
语法：
*斜体内容*_斜体内容_
|
|
|
|
呈现的效果：
前后各一个星号
前后各一个下划线
粗体
语法：
**粗体内容**__粗体内容__
|
|
|
|
呈现的效果：
前后各两个连续星号
前后各两个连续下划线
删除线
语法：
~~删除内容~~
|
|
|
|
呈现的效果：
前后各两个波浪线
组合
粗体、斜体以及删除线可以任意组合使用
|
|
|
|
呈现的效果：
斜体和粗体
删除线和粗体
删除线和斜体
删除线和斜体和粗体
换行
由空行分隔的文本块会被 Markdown 识别为段落，每段文本都将被置于一对 HTML 段落标记 <p> </p> 中。
（这里的“空行”指任何看上去“空”的行，任何只有空格或制表符而没有其他字符的行都会被 Markdown 识别为空行。）
换行方式有两种：
- 插入一个
空行另起段落换行，后续文本将被至于一对新的 HTML 段落标记<p> </p>中。 - 行末
空格空格回车段落内换行，相当于在行末添加 HTML 换行标记<br>。
|
|
|
|
呈现的效果：
第一段文本。（行末加 空格 空格 回车）
段落内换行。（下一行为空行）
空行后另起段落换行。
行距
段落间行距一般比段落内行距稍大。
引用
语法：
>空格引用文本
说明：
>个数对应引用层数- 引用 中可包含 标题、列表、代码块等其他 Markdown 格式。
|
|
|
|
呈现的效果：
本段展示引用效果。
引用可以嵌套：
|
|
|
|
呈现的效果：
这是第一层引用
这是第二层引用
这是第三层引用
列表
说明：
- 若列表项之间以空行分隔，则每个列表项中的文本将会被置于一对 HTML 段落标记
<p> </p>中。 - 若列表项内包含多段文本，则每段文本的首行需要缩进 4 空格或 1 制表符。
- 若列表项内包含 引用，则引用标识
>需要缩进 4 空格或 1 制表符。 - 若列表项内包含 代码块，则 代码块 文本需要缩进两次，即 8 空格或 2 制表符。
无序列表
语法：
*空格列表项+空格列表项-空格列表项
说明：
- 无序列表可依缩进嵌套
|
|
|
|
呈现的效果：
- 星号无序列表
- 星号无序列表
- 星号无序列表
- 嵌套的加号无序列表
- 嵌套的加号无序列表
- 嵌套的加号无序列表
- 减号无序列表
- 减号无序列表
- 减号无序列表
有序列表
语法：
数字.空格列表项
说明：
- 有序列表可依缩进嵌套
- 列表序号以第一个列表项的数字为基准，渲染时依次递增
- 若不希望意外生成有序列表，可将
.转义写作\.，如：2023\. What a great year.。
|
|
|
|
呈现的效果：
- 有序列表
- 有序列表 5. 嵌套的有序列表 4. 嵌套的有序列表 3. 嵌套的有序列表
- 有序列表
定义列表
语法：
- 术语
:空格定义内容
|
|
|
|
呈现的效果：
- 无序列表
- 列表项之间没有先后顺序关系，每个列表项前以
·为标记。 - 有序列表
- 列表项之间有先后顺序关系，每个列表项前以数字编号为标记。
任务列表
语法：
*/+/-空格[ ]列表项：未完成的任务列表*/+/-空格[x]列表项：已完成的任务列表
|
|
呈现的效果：
- 未完成的任务列表
- 已完成的任务列表
分割线
语法：
___（三个下划线，可不连续）---（三个减号，可不连续）***（三个星号，可不连续）
|
|
|
|
呈现的效果：
代码
说明：
- 代码 内的
&、<、>字符会被 Markdown 转义为&、<、>。 - 代码 内的 Markdown 语法不会被渲染。
行内代码
语法：
`代码内容`
|
|
|
|
呈现的效果：
在本行中，<section></section> 会被显示为 代码。
说明：
- 若需要在代码内容中包含
`，可用多个`作为代码的开始和结束分隔符, 如：
``这里有一个（`）符号``->这里有一个（`）符号。 - 若代码内容的收尾为
`，则可在开始和结束分隔符与代码内容间加空格，如：
行内代码语法：`` `代码内容` ``-> 行内代码语法：`代码内容`。
缩进代码
代码块中每行均使用连续 4 空格作为缩进，Markdonw 会将代码块内容置于 <pre><code> </code></pre> 标签中。
相应的，渲染过程中会移除代码块的一层缩进。
HTML 中的 <pre> 标签可定义预格式化的文本：保留空格和换行符，同时呈现为等宽字体。
|
|
|
|
呈现的效果：
一层缩进前段
二层缩进前段
三层缩进
二层缩进后段
一层缩进后段
代码块
语法：
```代码描述
代码内容
代码内容
```
说明：
代码描述通常为代码所采用的编程语言的文件扩展名，以供编辑器渲染语法高亮。
|
|
|
|
呈现的效果：
|
|
表格
|
|
|
|
呈现的效果：
| 表头 | 表头 | 表头 |
|---|---|---|
| 左对齐 | 居中对齐 | 右对齐 |
| 左对齐 | 居中对齐 | 右对齐 |
超链接
基本超链接
语法：
<超链接地址>[超链接文本](超链接地址)
|
|
|
|
呈现的效果（鼠标悬停在链接上时无标题提示）：
https://www.newverse.wiki
newverse@126.com
Newverse
标题超链接
语法：
[超链接文本](超链接地址空格"超链接标题")
|
|
|
|
呈现的效果（鼠标悬停在链接上时有标题提示）：
引用超链接
引用超链接 将 超链接文本 与 超链接地址 分离，
- 可通过
超链接标识重复引用相对应的超链接地址， - 可将
超链接标识和地址统一置于章节末尾或文档末尾，
使 Markdown 源文档更易于阅读。
语法：
[超链接文本][超链接标识][超链接标识]:空格超链接地址空格"超链接标题"
|
|
|
|
呈现的效果：
说明：为使 Markdown 文档更易阅读和书写，引用超链接 的语法规则更友好
超链接标题可被置于下一行并任意缩进，超链接标识不区分大小写，- 若
超链接标识与超链接文本一致，则可省略超链接文本之后的超链接标识只留：[超链接文本][]， 超链接标识行的两处空格可替换为任意长度空格或制表符，以使多行文本对齐。
因此，推荐 使用 引用式超链接 以进一步提高 Markdown 文本的可读性。
定位超链接
定位超链接 可跳转至同一页面上的指定位置。
语法：
- 指定位置
{#超链接标识} [超链接文本](#超链接标识)
说明：
#对应 CSS ID 选择器。
|
|
|
|
呈现的效果：
跳转至 -> 基本超链接
跳转至 -> 标题超链接
跳转至 -> 引用超链接
定位超链接 可以与 基础超链接 结合使用，跳转至指定页面的指定位置（一般为某级标题）。
语法：
[超链接文本](超链接地址#超链接标识)
|
|
|
|
呈现的效果：
John Gruber’s Markdown syntax # Links
脚注超链接
脚注超链接 可看作 引用超链接 与 定位超链接 的组合，可跳转至页尾或文末的脚注。
语法：
- 正文文本
[^脚注标识] [^脚注标识]:空格脚注内容
说明：
脚注标识可以是数字或单词，但不能包含空格及制表符。脚注标识仅在脚注符号与脚注内容间建立链接，在渲染时脚注按出现顺序编号。脚注内容可放在除 列表、引用 以及 表格 等元素之外文档中的任何位置，在渲染时会统一放置在文末。
|
|
|
|
呈现的效果：
这里有一个示例脚注1。
这里有第二个示例脚注2。
注意
Markdown 原始语法中并没有定义 脚注，其实现效果与具体的渲染器设置有关。
Hugo 采用的 Markdown 渲染器还为脚注内容添加了反向超链接，具体可查看上述 HTML 代码。
Hugo 采用的 Markdown 渲染器还为脚注内容添加了反向超链接，具体可查看上述 HTML 代码。
图片
图片 语法与 超链接 相似，只需在 超链接 前加一个感叹号 !。
基本图片
语法：
|
|
|
|
呈现的效果：
标题图片
语法：
![图片文本](图片地址空格"图片标题")
|
|
|
|
呈现的效果：
引用图片
语法：
![图片文本][图片标识][图片标识]:空格图片地址空格"图片标题"
|
|
|
|
呈现的效果：
注意
图片 的渲染结果由渲染器的具体设置决定，Hugo 的 Markdown 渲染器充分利用了 HTML 中的
<figure> 标签来显示 图片标题。转义字符
若希望在文本中使用上述被 Markdown 语法识别为 语法标识 的字符时，可使用转义符号 \，如：
\\-> \\`-> `\*-> *\_-> _\#-> #\+-> +\--> -\.-> .\!-> !\{\}-> {}\[\]-> []\(\)-> ()
内联 HTML 元素
可在 Markdown 文档中直接插入 HTML 标签、属性、样式等，从而获得 Markdown 中未定义的格式。
需要注意的是：
- 块级的 HTML 元素，如：
<div>``<table>``<pre>``<p>等，前后需要用空行去其他文本分隔开；且起止标签不能存在缩进。 - 块级的 HTML 标签中的 Markdown 语法不会被渲染，内联 HTML 元素标签中的 Markdown 语法会被渲染。
|
|
|
|
呈现的效果：
Markdown 格式的段落。
居中且标红的 HTML。
Markdown 格式的段落。
注释
利用 引用超链接 的 超链接标识 语法可以生成注释，且该注释不会出现在渲染生成的 HTML 文档中。
语法：
[注释内容]:空格#
说明：
- 上述格式实际是
超链接地址为空的 定位超链接 的 引用式 写法。 - 引用超链接 中
超链接标识在渲染时仅用于匹配超链接文本和超链接地址，不会出现在最终的 HTML 文档中。 - 建议在该注释前后各加一个空行，以保证其在各种渲染器下都能生效。
|
|
更一般的引入注释的方法是借用 HTML 中的注释：
|
|
|
|
呈现的效果（看不到下行的注释）：
缩进
语法：
或者 ：半个英文字符 或者⋒：一个英文字符 或者⋓：一个中文字符
|
|
呈现的效果：
No indent.
缩进半个英文字符。
缩进一个英文字符。
缩进一个中文字符。
无缩进。
参考资料：
- Markdown: Syntax - John Gruber
- Markdown 语法 - 繁体中文版
- Markdown 语法 - 简体中文版
- Markdown Guide：全面介绍 Markdown 相关内容。
- Goldmark：Hugo 默认使用的 Markdown 语法渲染器。
- CommonMark：GoldMark 遵循的 Markdown 语法规范。
- markdownlint：Markdown 语法检查和清洗工具。
- Markdown 写作，Pandoc 转换：我的纯文本学术写作流程：Markdown 转 Word 或 LaTeX 方法以及工具。