第2章 人人都能学会Markdown
2.1 基础语法
2.1.1 字体
1.标题
标题支持使用两种标记：底线（-/=）和#。
- 使用底线的语法如下。
说明：
- 底线是=表示一级标题。
- 底线是-表示二级标题。
- 底线符号的数量至少2个。
- 这种语法只支持这两级标题。
实例演示：
一级标题
=======
二级标题
-------
一级标题
二级标题
- 使用＃的语法如下。
说明：
- 在行首插入#可标记出标题。
-
的个数表示了标题的等级。
- 建议在#后加一个空格。
- Markdown中最多只支持前六级标题。
实例演示：
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
一级标题
二级标题
三级标题
四级标题
五级标题
六级标题
使用规范：
- 建议使用#标记标题，而不是===或-，因为后者会难以阅读和维护。
- 要保持间距，建议标题的前后都要空1行（除非标题在文档开头）；#与标题文本之间也要有1个空格，否则会导致阅读困难。
- 不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格。
- 建议标题的结尾不要有标点符号，如句号、逗号、冒号、分号等。
- 建议标题要尽量简短，这样方便引用，特别是当生成目录时。如果原拟的标题是一个长句，可以从长句中提取标题，而将长句作为标题下的内容。
使用Markdown写文档比较推荐的结构如下：
- 文档标题：文档的第一个标题应该是一级标题，写在第一行，建议与文件名相同，标题要尽量简短。
- 作者：可选，用于声明文档的作者，如果是开源项目的文档，建议把作者名写在修订历史中。
- 摘要：用1~3句话描述文档的核心内容。
- 目录：用于快速了解文档的结构，便于导航。
- 正文：正文中的标题从二级目录开始，逐级增加，不可跳级，不可相同。
2.粗体和斜体
- 粗体、斜体格式的语法
粗体由两个 * 或两个 _ 包裹，斜体由1个 * 或1个 _ 包裹
- 使用规范
推荐使用：粗体由两个 * ，斜体由1个 * 包裹
- 实例演示
我是**粗体**
我是*斜体*
我是粗体
我是斜体
说 明 ： 在粗体和斜体语法标记的内部，建议不要有空格。
2.1.2 段落与换行
Markdown中的段落由一行或多行文本组成，不同的段落之间使用空行来标记。
- 语法说明
- 如果行与行之间没有空行，则会被视为同一段落。
- 如果行与行之间有空行，则会被视为不同的段落。
- 空行是指行内什么都没有，或者只有空格和制表符。
- 如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。
- 实例演示
没有空行1
没有空行2
------
有空行1
有空行2
------
段内换行，要有空格
而且是二个以上的空格
没有空行1
没有空行2
有空行1
有空行2
段内换行，要有空格
而且是二个以上的空格
- 使用规范
为了便于阅读，应该限制每行字符的数量，通常每行不超过80个字符，可以在编辑器中进行设置。
- 当超过80个字符后进行换行。
- 在一句话结束（。或!或?）之后换行。
- 当URL较长时换行。通常URL较长会导致行字符数量超过限制，为了提高可读性，可以在URL之前加一个换行符。
1.列表
在Markdown中支持使用有序列表和无序列表。
-
语法如下
- 有序列表：数字序号 + 英文句号 + 空格 + 列表内容来标记
- 无序列表： * / + / - + 空格 + 列表内容来标记。
- 列表中可以嵌套列表。
- 有序列表和无序列表也可以互相嵌套。
实例演示
1. 有序列表1
2. 有序列表2
3. 有序列表3
4. 有序列表4
* 无序列表1
* 无序列表1
+ 无序列表2
+ 无序列表2
- 无序列表3
- 无序列表3
- 有序列表1
- 有序列表2
- 有序列表3
- 有序列表4
- 无序列表1
- 无序列表1
- 无序列表2
- 无序列表2
- 无序列表3
- 无序列表3
- 嵌套列表的语法
1. 有序嵌套列表1
2. 有序嵌套列表2
3. 有序嵌套列表3
4. 有序嵌套列表4
* 无序嵌套列表1
* 无序嵌套列表1
* 无序嵌套列表2
* 无序嵌套列表2
1. 有序无序嵌套列表
+ 有序无序嵌套列表
1. 有序无序嵌套列表
2. 有序无序嵌套列表
- 有序嵌套列表1
- 有序嵌套列表2
- 有序嵌套列表3
- 有序嵌套列表4
- 有序嵌套列表3
- 有序嵌套列表2
- 无序嵌套列表1
- 无序嵌套列表1
- 无序嵌套列表2
- 无序嵌套列表2
- 无序嵌套列表2
- 无序嵌套列表1
- 有序无序嵌套列表
- 有序无序嵌套列表
- 有序无序嵌套列表
- 有序无序嵌套列表
- 有序无序嵌套列表
- 使用规范
建议使用-来标记无序列表，因为 * 容易跟粗体和斜体混淆，而 + 不流行。
如果一个列表中所有的列表项都没有换行，建议使用1个空格。
- 推荐
- 推荐
- 不推荐
- 不推荐
推荐
推荐
不推荐
不推荐
如果列表项有换行，则建议给无序列表使用3个空格，给有序列表使用2个空格。
推荐
- 这个列表项
有换行
- 这个没有
1. 这个有序列表项
有换行
2. 这个没有
不推荐
- 这个列表项
有换行
- 这个没有
1. 这个有序列表项
有换行
2. 这个没有
如果一个列表中的每个列表项都只有1行，建议列表项之间不要有空行。
推荐
- 列表
- 列表
- 列表
不推荐
- 列表
- 列表
- 列表
如果列表项中有换行，建议在列表项之间空1行，这样会比较容易区分多行列表项的开始和结束。
推荐
- 列表
换行
- 列表
- 列表
不推荐
- 列表
换行
- 列表
- 列表
建议在列表前/后都空1行。
推荐
- 列表
- 列表
- 列表
推荐这样书写
不推荐
- 列表
- 列表
- 列表
推荐这样书写
数字、字符、符号列表使用英文半角句号，句号后加空格。
正确
1. 我是好人
2. 他是好人
3. 你也是好人
不正确
1。我是好人
2、他是好人
3.你也是好人
正确
a. 我是好人
b. 他是好人
不正确
a.我是好人
b.他是好人
2.分隔线
在Markdown中，分隔线由3个以上的* / - / _ 来标记。
- 使用分割线的语法
******
------
______
- 语法说明
***
* * *
******
---
- - -
------
___
_ _ _
______
- 分隔线须使用至少3个以上的 * / - / _ 来标记。
- 行内不能有其他的字符。
- 可以在标记符中间加上空格。
2.1.3 图片
-
插入图片的语法
[图片上传失败...(image-d5fb1e-1629779057894)] 语法说明
- 图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。
- 图片地址可以是本地图片的路径也可以是网络图片的地址。
- 本地图片支持相对路径和绝对路径两种方式。
- 实例演示
这是本地图片与网络图片
本地图片只能在本地上存放查看，由于上传到网上就是网络图片了，故无法展示
2.1.4 链接
1.文字链接
文字链接就是把链接地址直接写在文本中。语法是用方括号包裹链接文字，后面紧跟着括号包裹的链接地址
-
语法格式
[链接文字](链接地址) 实例演示
github官网地址在[这里](https://github.com/)
github官网地址在这里
也可以有另一种写法，目的是为了防止文字与链接写在一起
github官网地址在[这里]，而我最常用的还是[百度]来搜索东西，或者是[天猫]来购物
[这里]: https://github.com/
[百度]: https://www.baidu.com/
[天猫]: https://www.tmall.com/
github官网地址在这里，而我最常用的还是百度来搜索东西，或者是天猫来购物
说明： 把链接地址在某个地方统一定义好，然后在正文中通过“变量 ”来引用，可读性一下子就变强了，这种方法叫作引用链接。
2.引用链接
- 语法格式
在正文中引用链接标记，可以理解为引用定义好的变量
[连接文字][链接标记]在底部定义链接标记，可以理解为定义一个地址变量
[链接标记][链接地址]
- 语法说明
- 链接标记可以有字母、数字、空格和标点符号。
- 链接标记不区分大小写。
- 定义的链接内容可以放在当前文件的任意位置，建议放在页尾。
- 当链接地址为网络地址时要以 http/https开头，否则会被识别为本地地址。
3.网址链接
将网络地址或邮箱地址使用<>包裹起来会被自动转换为超链接。
-
语法格式
<URL 或邮箱地址 >
实例演示
<https://www.baidu.com>
<myEmail@126.com>
https://www.baidu.com
myEmail@126.com
4.使用规范
链接标题的信息应该更丰富，从标题中应该可以知道链接的内容，要使用有意义的链接标题。建议使用<>包裹自动链接，这种方式更通用。
2.1.5 行内代码与代码块
1.行内代码
行内代码引用使用 ` 包裹
- 语法格式
`代码`
- 实例演示
使用`cd ..`进入上一级命令
使用`mkdir`创建文件夹
使用cd ..进入上一级命令
使用mkdir创建文件夹
2.代码块
代码块以Tab键或4个空格开头
以tab键开头
def fun():
print(3+4)
以四个空格开头
def fun():
print(3+4)
以tab键开头
def fun():
print(3+4)
以四个空格开头
def fun():
print(3+4)
小提示： 因为代码块使用Tab键或4个空格开头的效果不够直观，很多扩展语法（如GFM）提供了围栏代码块，并且支持语法高亮。
3.使用规范
- 除行内代码可以使用 ` 包裹以外，如果我们想转义或强调某些字符，也可以使用 ` 包裹。
若你想删库跑路可以执行`rm -rf /`
若你不想想删库`跑路`可以查看手册
若你想删库跑路可以执行rm -rf /
若你不想想删库跑路可以查看手册
-
如果代码超过1行，请使用围栏代码块（扩展语法），并显式地声明语言，这样做便于阅读，并且可以显示语法高亮。但如果我们编写的是简单的代码片段，使用4个空格缩进的代码块也许更清晰。
```python def fun(): print(3+4) ```
进入上一级命令
cd ..
-
很多Shell命令都要粘贴到终端中去执行，因此最好避免在Shell命令中使用任何换行操作；可以在行尾使用一个\，这样既能避免命令换行，又能提高源码的可读性。
```shell jvs run --test=test/home/test_login.py::test_login_failed --env=online \ --username="XXX" --password="xxx" --url="https://www.baidu.com" ``` 建议不要在没有输出内容的Shell命令前加 $ 。在命令没有输出内容的情况下， $ 是没有必要的，因为内容全是命令，我们不会把命令和输出的内容混淆。
建议在有输出内容的Shell命令前加上$，这样会比较容易区分命令和输出的内容。
2.1.6 引用
引用由 > + 引用内容来标记
- 语法说明
- 多行引用也可以在每一行的开头都插入 > 。
- 在引用中可以嵌套引用。
- 在引用中可以使用其他的Markdown语法。
- 段落与换行的格式在引用中也是适用的。
- 实例演示
引用
> 引用句子
多行引用
> 多行引用第一行，最后要有两个空格
> 多行引用第二行
多行引用
> 多行引用第一行
> 多行引用第二行
引用嵌套引用
> 多行引用第一行
> > 多行引用第二行
引用中使用其他Md标记
> 这个是[github链接](https://github.com/)
> **加粗**和*斜体*夜之城
引用
引用句子
多行引用
多行引用第一行，最后要有两个空格
多行引用第二行
多行引用
多行引用第一行
多行引用第二行
引用嵌套引用
多行引用第一行
多行引用第二行
引用中使用其他Md标记
这个是github链接
加粗和斜体夜之城
2.使用规范
- 建议在引用的标记符号＞之后添加一个空格。
- 建议每一行引用都使用符号＞。
- 不要在引用中添加空行。
2.1.7 转义
当想在Markdown文件中插入一些标记符号，但又不想让这些符号被渲染时，可以使用 \ 进行转义
-
语法格式
\特殊符号
- 可被转义的特殊符号
\ 反斜杠
` 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
+ 加号
- 减号
. 英文句点
! 感叹号
- 实例演示
\\
\`
\*
\_
\{\}
\[\]
\
`
*
_
{}
[]
2.2 扩展语法GFM
在众多Markdown扩展语法中，GitHub Flavored Markdown（简称GFM）无疑是目前最流行的，它提供了包括表格、任务列表、删除线、围栏代码、Emoji等在内的标记语法
2.2.1 删除线
- 语法格式
~~删除的文字~~
- 实例演示
~~删除的文字~~
不支持换行删除，~~我说的是真的。
你要是不信就是自己试试~~
删除的文字
支持换行删除，我说的是真的。
你要是不信就是自己试试
2.2.2 表情符号
使用：包裹表情代码即可
-
语法格式
:表情代码: 实例演示
:boy:
:cupid:
:girl:
:unamused:
:boy:
:cupid:
:girl:
:unamused:
2.2.3 自动链接
由 <> 包裹的URL地址被自动识别并解析为超链接，使用GFM扩展语法则可以不使用 <> 包裹。
标准语法中由 <> 包裹的URL地址被自动识别并解析为超链接
<https://www.baidu.com>
使用GFM扩展语法则可以不使用 <> 包裹
https://www.baidu.com
注意： 自动链接只识别以www或http://开头的URL地址。如果不想使用自动链接，也可以使用 ` 包裹URL地址如下
2.2.4 表格
-
表格的语法
|表头1|表头2|表头3| |---|---|---| |内容1|内容2|内容3| |内容1|内容2|内容3| 语法说明
- 单元格使用|来分隔，为了阅读更清晰，建议最前和最后都使用|。
- 单元格和|之间的空格会被移除。
- 表头与其他行使用-来分隔。
- 表格对齐格式如下。
○ 左对齐（默认）：:
○ 右对齐：-:
○ 居中对齐：:-: - 块级元素（代码区块、引用区块）不能插入表格中。
- 实例演示
表格格式
|表头1|表头2|表头3|
|---|---|---|
|内容1|内容2|内容3|
|内容1|内容2|内容3|
对齐格式
|左对齐|右对齐|居中对齐|
|:---|---:|:---:|
|1|github|https://github.com/|
|2|CSDN|https://mp.csdn.net/|
表格内使用其他标记
|序号|标题|网址|
|---|---|---|
|**1（加粗）**|github|https://github.com/|
|*2（斜体）*|CSDN|https://mp.csdn.net/|
表格格式
| 表头1 | 表头2 | 表头3 |
|---|---|---|
| 内容1 | 内容2 | 内容3 |
| 内容1 | 内容2 | 内容3 |
对齐格式
| 左对齐 | 右对齐 | 居中对齐 |
|---|---|---|
| 1 | github | https://github.com/ |
| 2 | CSDN | https://mp.csdn.net/ |
表格内使用其他标记
| 序号 | 标题 | 网址 |
|---|---|---|
| 1（加粗） | github | https://github.com/ |
| 2（斜体） | CSDN | https://mp.csdn.net/ |
- 创建表格的建议
- 在表格的前、后各空1行。
- 在每一行最前和最后都使用|，每一行中的|要尽量都对齐。
- 不要使用庞大复杂的表格，那样会难以维护和阅读。
2.2.5 任务列表
- 语法格式
- [ ] 未勾选
- [x] 已勾选
- 语法说明
- 任务列表以 - + 空格开头，由 [ + 空格 / x + ] 组成。
- x可以小写，也可以大写，有些编辑器可能不支持大写，所以为避免解析错误，推荐使用小写的x。
- 当方括号中的字符为空格时，复选框是未选中状态，为x时是选中状态。
- 实例演示
任务进度1
+ [x] 第一阶段
+ [ ] 第二阶段
+ [ ] 第三阶段
任务进度详细2
+ [x] 第一阶段
+ [ ] 第1阶段
+ [ ] 第2阶段
+ [x] 第二阶段
+ [x] 第1阶段
+ [ ] 第2阶段
任务进度1
- 第一阶段
- 第二阶段
- 第三阶段
任务进度详细2
- 第一阶段
- 第1阶段
- 第2阶段
- 第二阶段
- 第1阶段
- 第2阶段
2.2.6 围栏代码块
在基础语法中，代码块使用Tab键或4个空格开头；在扩展语法中，围栏代码块使用连续3个 ` 或3个 ~ 包裹，还支持语法高亮，可读性和可维护性更强一些。
-
语法格式
``` 代码片段 ``` 或者 ~~~ 代码片段 ~~~ 语法高亮 ```python 代码片段 ``` 语法说明
围栏代码块使用连续3个`或3个~包裹，支持语法高亮并可以加上编程语言的名字。
-
实例演示
``` def fun(): pass ``` ~~~ def fun(): pass ~~~ ```python def fun(): pass ``` ~~~python def fun(): pass ~~~
def fun():
pass
def fun():
pass
def fun():
pass
def fun():
pass
建议围栏代码块被空行包裹。
2.2.7 锚点
锚点，也称为书签，用来标记文档的特定位置，使用锚点可以跳转到当前文档或其他文档中指定的标记位置。
Markdown会被渲染成HTML页面，在HTML页面中可以通过锚点实现跳转；GitHub、GitBook项目文档中的目录也是通过锚点实现跳转的。
-
语法格式
[锚点描述](#锚点名) 语法说明
- 锚点名建议使用字母和数字，当然中文也是被支持的，但不排除有些网站支持得不够好。
- 锚点名是区分英文大小写的。
- 在锚点名中不能含有空格，也不能含有特殊字符。
- 实例演示
目录
[第一段](#第01段)
[第二段](#第02段)
第01段 巴拉巴拉
第02段 bala bala
目录
第01段 巴拉巴拉
第02段 bala bala
注意： 笔者发现以上两种似乎支持并不是很好，所以建议参考别的文章来实现锚点，笔者找到了CSDN的一篇参考：https://blog.csdn.net/weixin_45844049/article/details/103866977
2.3 排版技巧
2.3.1 推荐的排版样式
下面有两个比较好的排版示例，注意观察它们是如何使用段落、数字、英文和标点符号的。
[图片上传失败...(image-dc3f93-1629779057895)]
上面左图是受关注比较多的技术公众号“谷歌开发者”的版面，右图是付费学习平台“得到”的版面。
2.3.2 关于空格
建议中文和英文之间加空格，中文/英文和数字之间也要加空格，不过有些编辑器和输入法（如百度输入法）会自动添加空隙，我们就没必要手动添加了，大家在使用时请多注意。
1. 一些需要加空格的情况
- 英文标点符号（如,.;:?）与后面的字符之间需要加空格，与前面的字符之间不需要加空格。
- 当在中文、英文中使用＞（半角）标识路径时，两边都需要加空格。
2. 不加空格的情况
- 中文标点符号和数字、中文、英文之间不需要添加空格。
- 数字和百分号之间不需要添加空格。
- 数字和单位符号之间不需要添加空格。
- 英文和数字组合成的名字之间不需要添加空格。
- 当 / （半角）表示“或”、“路径”时，与前后的字符之间均不加空格。
- 货币符号后不加空格。
- 负号后不加空格。
2.3.3 全角和半角
全角：中文标点符号是全角，占两个字节。
半角：英文标点符号和数字是半角，占1个字节。
全角：，。；：!#
半角：,.;:!#
- 在中文排版中，要使用全角标点符号。
- 在英文排版中，要使用半角标点符号。
2.3.4 正确的英文大小写
很多人在文章、邮件甚至简历中，会把专有名词写错，虽然这并不会影响人们对内容的理解，但有时的确会让人觉得你不太“专业”。专有名词要使用正确的大小写，请参考它们的官方文档。
2.4 本章小结
学完本章以后，相信你已经可以使用 Markdown 写作了，对于文章的排版也一定有了很多新的认识。不过要记住这么多语法规范确实不太容易，还好很多编辑器（如Typora）已经帮我们规避了那些容易出错的地方，VS Code也有插件能够进行语法检查。
