Markdown 是一种轻量级的标记语言,它允许你使用易于阅读和编写的纯文本格式来创建结构化的文档。Markdown 的设计目标是尽可能地易读易写。它被广泛应用于编写文档、笔记、博客、书籍以及在各种在线平台上进行内容创作。本教程手册将全面介绍 Markdown 的基本语法和扩展语法,并提供一些实用的技巧,助你快速上手并精通 Markdown。
如果你还不知道 Markdown 是什么,请阅读文章:什么是 Markdown?一文带你了解这个内容创作者的效率神器
💡 为方便查看本手册中的 Markdown 语法渲染效果,可以将 Markdown 语法示例复制到 「人言兑.md」 中进行预览(人言兑.md 是一个使用 Markdown 语法编写公众号文章的在线编辑器,点击 这里 了解详情)。
Markdown 基本语法
以下是 Markdown 的核心语法元素,它们在所有 Markdown 应用中都应该被支持。
标题 (Headings)
Markdown 语法中支持六级标题,通过在行首添加 # 符号来定义标题级别,# 的数量对应标题的级别。
# 一级标题
渲染为<h1>一级标题</h1>
## 二级标题
渲染为<h2>二级标题</h2>
### 三级标题
渲染为<h3>三级标题</h3>
#### 四级标题
渲染为<h4>四级标题</h4>
##### 五级标题
渲染为<h5>五级标题</h5>
###### 六级标题
渲染为<h6>六级标题</h6>
另外,还可以使用 = 和 - 来创建一级和二级标题:
一级标题
========
二级标题
--------
最佳实践:
- 在 # 符号和标题文本之间添加一个空格。
- 为了兼容性,在标题前后添加空行。
段落 (Paragraphs)
Markdown 语法中的段落由一个或多个文本行组成,使用空行来分隔不同的段落。
这是第一段。
这是第二段。
最佳实践:不要使用空格或制表符缩进段落,除非段落位于列表中。
换行 (Line Breaks)
Markdown 语法中,在一行的末尾添加 两个或多个空格,然后键入回车来创建一个换行。你也可以使用 <br>
HTML 标签来换行。
最佳实践: 为了兼容性,建议使用尾随空格或 <br>
标签。
粗体 (Bold)
Markdown 语法支持两种强调方式:使用 两个星号 () 或 两个下划线 (__) 将文本括起来。
**粗体文本**
或 __粗体文本__
渲染为 <strong>粗体文本</strong>
。
**这是粗体文本**
__这也是粗体文本__
最佳实践:为了兼容性,使用星号来加粗单词中间部分。 例如: Love**is**bold
,同时,建议在加粗的中文文本的前后添加空格。
斜体 (Italic)
Markdown 语法使用 一个星号 *
或 一个下划线 _
包裹需要斜体的文本。
*斜体文本*
或 _斜体文本_
渲染为 <em>斜体文本</em>
。
_这是斜体文本_
_这也是斜体文本_
最佳实践:为了兼容性,建议在单词中间使用星号 *
来倾斜。 例如:A*cat*meow
粗体和斜体 (Bold and Italic)
Markdown 语法使用 三个星号 ***
或 三个下划线 ___
包裹需要同时加粗和斜体的文本。
***这是粗斜体文本***
___这也是粗斜体文本___
最佳实践:
- 为了兼容性,使用星号来斜体加粗单词中间部分。
- 使用
**_粗斜体_**
或_**粗斜体**_
更加直观。
引用 (Blockquotes)
在段落前添加 > 符号来创建引用。
> 这是引用的内容
>
> 这是引用的内容
>
> 这是引用的内容
最佳实践:在引用前后各留一个空行,以确保正确渲染。
引用可以包含其他 Markdown 格式的元素进行嵌套引用,使用多个 >
符号来创建嵌套引用
> 这是第一层引用
> > 这是第二层引用
> > > 这是第三层引用
列表 (Lists)
Markdown 语法支持有序列表和无序列表。
有序列表 (Ordered Lists)
使用 数字加英文句点 .
来创建有序列表。 数字不必按顺序排列,但列表应该以数字 1 开始。
1. 第一项
2. 第二项
3. 第三项
最佳实践:为了兼容性,列表项分隔符建议只使用英文句点 .
。
无序列表 (Unordered Lists)
使用 减号 -
、星号 *
或 加号 +
来创建无序列表。
- 第一项
* 第二项
+ 第三项
最佳实践:
- 在同一个列表中,不要混合使用不同的分隔符。
- 要使无序列表的条目以数字开头,需要使用反斜杠 (
\
) 进行转义。 例如:- 1968\. A great year!
嵌套列表 (Nested Lists)
可以通过缩进列表项来创建嵌套列表。
1. 第一项
1. 嵌套第一项
2. 嵌套第二项
2. 第二项
在列表中添加其他元素
要在列表中添加其他元素(如段落、引用或代码块),需要将这些元素缩进。
- 这是第一项。
- 这是第二项。
这是第二项下的一个段落。
- 这是第三项。
代码 (Code)
Markdown 语法中可以使用两种方式来标记代码:行内代码 和 代码块。
行内代码 (Code Spans)
使用 反引号 `
包裹行内代码。
`这是行内代码`
如果代码本身包含反引号,可以使用 双反引号 (``) 来包裹。
`` 这是包含 ` 反引号的代码 ``
最佳实践:
- 注意
``
首尾的空格 - 行内代码中的反斜杠不会被转义 例如:
\`
不会被渲染成`
代码块 (Code Blocks)
可以使用两种 Markdown 语法来创建代码块:缩进和围栏式。
缩进式代码块:将代码块的每一行缩进 至少四个空格 或一个制表符。
<html>
<head>
</head>
</html>
围栏式代码块:使用 三个反引号 ```
或 三个波浪号 ~~~
将代码块包裹起来,可以在开头的反引号或波浪号后添加代码语言的名称,以进行语法高亮。
```python
def hello():
print("Hello, world!")
```
~~~html
<html>
<head>
</head>
</html>
~~~
最佳实践:围栏式代码块更易于使用和阅读,并且支持语法高亮。
分割线 (Horizontal Rules)
Markdown 语法使用 三个或更多星号 ***
、减号 ---
或 下划线 ___
来创建水平分割线。
***
、---
或 ___
渲染为 <hr />
。
---
***
+++
最佳实践:在水平分割线前后各留一个空行。
链接 (Links)
Markdown 语法中如何添加 URL 链接?
行内链接 (Inline Links)
使用 方括号 []
包裹链接文本,紧接着使用 圆括号 ()
包裹 URL 链接地址。
[链接文本](https://www.example.com)
还可以在 URL 后面的圆括号中添加链接标题。
[链接文本](https://www.example.com "链接标题")
可以使用 尖括号 <>
来快速将 URL 或邮箱地址转换为链接。
<https://www.example.com>
<test@example.com>
格式化链接
使用星号 *
可以强调链接: **[链接](url)**
, *[链接](url)*
**[链接文本](https://www.example.com)**
*[*链接文本*](https://www.example.com)*
使用反引号将链接表示为代码: [`code`](url)
引用式链接 (Reference Links)
引用链接将链接的定义与文本分开,提高了 Markdown 的可读性。
引用式链接分为两部分:链接文本 和 链接定义。链接文本在文中直接使用,链接定义则放在文档的其他地方。
[链接文本][标签]
[标签]: https://www.example.com "链接标题"
链接文本使用两个方括号 [链接文本][标签]
。
链接定义可以出现在文档的任何地方,其格式是: [标签]: URL "链接标题"
标签不区分大小写。链接的定义部分可以放在文章结尾或段落后方。
最佳实践:
- URL 中如果包含空格,建议使用
%20
编码空格,或者使用<a>
标签。 - URL 中如果包含括号,建议分别使用
%28
和%29
来编码左右括号,或使用<a>
标签。
图片 (Images)
Markdown 图片语法类似于链接,只是在最前面添加一个 感叹号 !
。
![图片描述](image.jpg)
还可以在 URL 之后的圆括号内添加图片标题:
![图片描述](image.jpg "图片标题")
链接图片: 将图片 Markdown 语法用方括号括起来,然后在后面用圆括号括住链接地址。
[![alt text](image.jpg)](https://www.example.com)`
引用式图片:
![图片描述][图片标签]
[图片标签]: image.jpg "图片标题"
转义字符 (Escaping Characters)
Markdown 语法使用 反斜杠 \
来转义 Markdown 中的特殊字符。 例如:\*
将显示为 * 而不是斜体。
可以转义的字符包括:
- 反斜杠
\
- 反引号
`
- 星号
*
- 下划线
_
- 花括号
{}
- 方括号
[]
- 尖括号
<>
- 圆括号
()
- 井号
#
- 加号
+
- 减号
-
- 句点
.
- 感叹号
!
- 竖线
|
HTML 元素
可以在 Markdown 中直接使用 HTML 标签,当需要修改元素的属性时,使用 HTML 更方便,但并非所有 Markdown 应用都支持 HTML。
最佳实践:
- 使用空行分隔块级 HTML 元素,例如
<div>
、<table>
、<pre>
和<p>
。 - 不要用制表符或空格缩进 HTML 标签。
- 不能在块级 HTML 标签中使用 Markdown 语法
Markdown 扩展语法
扩展语法是在基本语法的基础上添加的增强功能。并非所有的 Markdown 应用都支持这些扩展语法元素。
删除线 (Strikethrough)
使用 两个波浪号 ~~
包裹需要添加删除线的文本。
~~这是删除线文本~~
~~被删除的文字~~
渲染为 <del>被删除的文字</del>
。
任务列表 (Task Lists)
Markdown 语法使用 减号和方括号 - [ ]
创建任务列表,使用 - [x]
来标记已完成的任务。
- [x] 已完成的任务
- [ ] 未完成的任务
表情符号 (Emoji)
可以直接复制粘贴 emoji 或者使用 emoji 简码。例如: :joy:
会显示 😂
注意: 表情符号简码在不同应用中可能不同。
下标 (Subscript)
Markdown 语法使用 一个波浪号 ~
包裹下标文本。
H~2~O
H~2~O
渲染为 H<sub>2</sub>O
最佳实践:可以在 HTML 中使用 <sub>
标签来实现下标。例如 H<sub>2</sub>O
。
上标 (Superscript)
使用 一个插入符号 ^
包裹上标文本。
X^2^
X^2^
渲染为 X<sup>2</sup>
最佳实践:可以在 HTML 中使用 <sup>
标签来实现上标。例如 X<sup>2</sup>
。
自动 URL 链接 (Automatic URL Linking)
许多 Markdown 处理器会自动将 URL 转换为链接。 例如:http://www.example.com 会被自动转换为链接。
使用反引号 `
将 URL 括起来,以禁用自动链接: `http://www.example.com`
表格 (Tables)
Markdown 语法使用 三个或多个减号 (—) 创建表头,并使用 竖线 (|) 分隔列。
| 表头 1 | 表头 2 |
| ------ | ------ |
| 内容 1 | 内容 2 |
Markdown 表格语法最佳实践:
- 为了兼容性,在每一行的开头和结尾添加竖线。
- 表格单元格的宽度可以不同,渲染结果保持一致。
- 表格中不能使用标题、引用、列表、水平线、图像或大多数 HTML 标签。
- 可以在表格中使用 HTML
<br>
标签来实现单元格内的换行和使用<ul>
<li>
等标签来创建列表。 - 转义表格中的竖线: 使用
|
来在表格中显示竖线。
脚注 (Footnotes)
使用 [^数字]
来创建脚注标记,并在文档的其他地方使用 [^数字]:
来定义脚注内容。
这是一个带有脚注的句子。[^1]
[^1]: 这是脚注的内容。
脚注会在输出中按顺序编号。
注意: 标识符不能包含空格或制表符。
标题 ID (Heading IDs)
Markdown 可以使用 { #custom-id }
为标题添加自定义 ID,方便链接到文档内的特定部分。
## My Great Heading {#custom-id}
链接到标题 ID:
- 可以使用
#
符号后跟自定义 ID 来创建链接。例如:[点击这个链接文本跳转到#custom-id 的位置](#custom-id)`
- 其他网站可以通过在网页 URL 后添加自定义 ID 来链接到该标题。例如:
[链接文本](https://www.example.com/extended-syntax#custom-id)
定义列表 (Definition Lists)
可以使用 term : definition
来创建定义列表。在第一行键入术语,在下一行键入冒号加空格,然后是定义。
术语
: 定义 1
: 定义 2
高亮 (Highlights)
使用 ==
包裹需要高亮的文本。
==需要高亮的文字==
也可以使用 <mark>
标签: <mark>高亮文本</mark>
Markdown 技巧
以下是一些在 Markdown 中进行高级操作的技巧,这些技巧并非所有应用都支持。
下划线 (Underline)
Markdown 本身不支持下划线,可以使用 <ins>
HTML 标签来实现。
<ins>下划线文字</ins>
渲染为 下划线文字
缩进 (Indent)
Markdown 对缩进有特殊含义,通常使用空格键或制表符缩进段落是不起作用的,但是可以使用以下方式实现:
- 使用 Markdown 编辑器支持缩进的功能。
- 使用
HTML 实体来创建缩进。 - 例如:
这是缩进的段落。
居中 (Center)
Markdown 本身没有居中对齐的概念,可以使用 <center>
HTML 标签来实现。
<center>居中文本</center>
也可以可以使用 CSS text-align:center
属性来实现居中, 例如:
<p style="text-align:center">居中文本</p>
颜色 (Color)
Markdown 本身没有改变文本颜色的功能,可以使用 <font>
HTML 标签来实现。
<font color="red">红色文字</font>
渲染为 红色文字
可以使用 CSS color:blue
属性来改变颜色, 例如:
<p style="color:blue">蓝色文本</p>
注释 (Comments)
使用 [注释]: #
这种格式添加隐藏注释。
这是可见的段落。
[这是一个注释]: #
这是另一个可见的段落。
最佳实践: 在注释前后添加空行。
提示框 (Admonitions)
可以使用引用和表情符号以及加粗文本来模拟提示框。
> :warning: **警告:** 这是警告提示。
> :memo: **注意:** 这是注意提示。
> :bulb: **技巧:** 这是技巧提示。
图片大小 (Image Size)
使用 <img>
HTML 标签的 width
和 height
属性来调整图片大小。例如:
<img src="image.png" width="200" height="100">
图片标题 (Image Captions)
可以使用 <figure>
和 <figcaption>
HTML 标签来为图片添加标题。
<figure>
<img src="image.jpg" alt="图片描述" />
<figcaption>这是图片标题</figcaption>
</figure>
也可以直接在图片下方添加文本,使用斜体强调,作为图片标题。
链接目标 (Link Targets)
可以使用 <a>
HTML 标签的 target="_blank"
属性来让链接在新标签页中打开。
例如:
<a href="https://www.example.com" target="_blank">在新标签页打开链接</a>
符号 (Symbols)
直接复制粘贴符号到 Markdown 文档中,也可以使用 HTML 实体代码来插入符号。
例如: ©
渲染为 ©
常见 HTML 实体代码:
©
(版权符号 ©)®
(注册商标符号 ®)™
(商标符号 ™)€
(欧元符号 €)←
(左箭头 ←)↑
(上箭头 ↑)→
(右箭头 →)↓
(下箭头 ↓)°
(度 °)π
(圆周率 π)
表格格式化 (Table Formats)
表格内换行: 使用 <br>
标签来分隔表格内的段落。
表格内列表: 使用 HTML 标签 (<ul>
, <li>
)来在表格中添加列表。
目录 (Table of Contents)
有些 Markdown 应用可以自动生成目录,但是如果你的应用不支持此功能,可以使用列表和链接手动创建目录。
- [链接文本 1](#heading-id-1)
- [链接文本 2](#heading-id-2)
- [链接文本 3](#heading-id-3)
需要在文章中使用对应的标题 ID。
视频 (Videos)
如果应用支持 HTML, 可以直接嵌入视频网站提供的 HTML 代码。如果应用不支持,可以使用图片和链接来模拟视频嵌入。
[![视频标题](视频封面图.jpg)](视频链接)
CommonMark 规范
CommonMark 是一份对 Markdown 语法的标准化规范。以下是一些重要概念:
- 字符和行:任何字符序列都是有效的 CommonMark 文档。字符是 Unicode 编码点。
- 空格字符:包括 Unicode Zs 类别的字符、制表符(U+0009)、换行符(U+000A)、换页符(U+000C)和回车符(U+000D)。
- 制表符:制表符不展开为空格,但在需要空格定义块结构时,制表符的表现如同被替换为制表符停止位为 4 个字符的空格。
- 不安全字符:Unicode 字符 U+0000 必须替换为替换字符(U+FFFD)。
- 反斜杠转义:任何 ASCII 标点字符都可以被反斜杠转义。反斜杠后的其他字符被视为字面反斜杠,转义字符会被视为常规字符,失去 Markdown 的特殊含义。
- 实体引用:实体引用由
&
+ HTML5 实体名称 +;
组成。例如&
代表&
,©
代表©
。 - 数字字符引用:十进制字符引用由
&#
+ 1-7 位阿拉伯数字 +;
组成,例如:#
代表#
。十六进制字符引用由&#
+x
或X
+ 1-6 位十六进制数字 +;
组成,例如"
代表"
。 - HTML 块:HTML 块是指由 HTML 标签组成的块,其起始和结束条件由特定规则定义。
- 容器块:包括块引用和列表项。列表是列表项的元容器。
- 列表项:列表项的标记可以是项目符号或有序列表标记。项目符号列表标记使用
-
,+
或*
;有序列表标记使用 1-9 位数字后跟.
或)
。 - 内联元素:Markdown 的内联元素按从左到右的顺序解析,包括代码跨度、强调、链接、图片等。
- 代码跨度:由反引号包裹,内容会进行规范化处理,例如删除首尾空格。
- 强调和加粗:使用
*
或_
实现强调,使用**
或__
实现加粗,具体的规则较复杂。 - 链接和图片:链接使用
[]
和()
,图片语法类似于链接,只是在前面添加一个!
。 - 自动链接:使用尖括号
<>
包裹 URL 会被自动解析为链接。 - 原始 HTML:在尖括号
<>
中看起来像 HTML 标签的文本会被解析为原始 HTML。
关键点:
- 强调和加粗的规则:需要注意左侧和右侧的定界符,以及 Unicode 标点符号的影响。
- 代码跨度:代码跨度的优先级高于除 HTML 标签和自动链接外的其他内联结构。
- 链接:注意链接文本和链接地址的语法,以及如何使用引用式链接。
- HTML 块:了解 HTML 块的起始和结束条件,以及如何在 Markdown 中使用 HTML 标签。
- 列表:需要了解列表的类型,列表项的标记,以及列表的嵌套和懒惰延续行规则。
总结
本教程手册涵盖了 Markdown 的基本语法、扩展语法和一些实用技巧。Markdown 的目标是简化文档编写,让你专注于内容而不是格式。通过掌握这些语法,你可以更高效地创建结构化的文档。希望本教程手册能帮助你更好地使用 Markdown。
请注意,某些特性可能因不同的 Markdown 解析器而有所不同。为了获得最佳效果,请查阅你正在使用的特定 Markdown 应用的文档。