《了不起的Markdown》第二章

2.1 基础语法

2.1.1 字体

1.标题

标题支持使用两种标记&＃xff1a;底线&＃xff08; - / &＃61; &＃xff09;和 # 。

• 使用底线的语法如下。

说明&＃xff1a;

1. 底线是&＃61;表示一级标题。
2. 底线是-表示二级标题。
3. 底线符号的数量至少2个。
4. 这种语法只支持这两级标题。

实例演示&＃xff1a;

一级标题
&＃61;&＃61;&＃61;&＃61;&＃61;&＃61;&＃61;
二级标题
-------

一级标题

二级标题

• 使用&＃xff03;的语法如下。

说明&＃xff1a;

1. 在行首插入#可标记出标题。
2. #的个数表示了标题的等级。
3. 建议在#后加一个空格。
4. Markdown中最多只支持前六级标题。

实例演示&＃xff1a;

# 一级标题## 二级标题### 三级标题#### 四级标题##### 五级标题###### 六级标题

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

使用规范&＃xff1a;

1. 建议使用#标记标题&＃xff0c;而不是&＃61;&＃61;&＃61;或-&＃xff0c;因为后者会难以阅读和维护。
2. 要保持间距&＃xff0c;建议标题的前后都要空1行&＃xff08;除非标题在文档开头&＃xff09;&＃xff1b;#与标题文本之间也要有1个空格&＃xff0c;否则会导致阅读困难。
3. 不要有多余的空格。建议标题要写在一行的开头&＃xff0c;结尾也不要有空格。
4. 建议标题的结尾不要有标点符号&＃xff0c;如句号、逗号、冒号、分号等。
5. 建议标题要尽量简短&＃xff0c;这样方便引用&＃xff0c;特别是当生成目录时。如果原拟的标题是一个长句&＃xff0c;可以从长句中提取标题&＃xff0c;而将长句作为标题下的内容。

使用Markdown写文档比较推荐的结构如下&＃xff1a;

1. 文档标题&＃xff1a;文档的第一个标题应该是一级标题&＃xff0c;写在第一行&＃xff0c;建议与文件名相同&＃xff0c;标题要尽量简短。
2. 作者&＃xff1a;可选&＃xff0c;用于声明文档的作者&＃xff0c;如果是开源项目的文档&＃xff0c;建议把作者名写在修订历史中。
3. 摘要&＃xff1a;用1~3句话描述文档的核心内容。
4. 目录&＃xff1a;用于快速了解文档的结构&＃xff0c;便于导航。
5. 正文&＃xff1a;正文中的标题从二级目录开始&＃xff0c;逐级增加&＃xff0c;不可跳级&＃xff0c;不可相同。

2.粗体和斜体

• 粗体、斜体格式的语法

粗体由两个 * 或两个 _ 包裹&＃xff0c;斜体由1个 * 或1个 _ 包裹

• 使用规范

推荐使用&＃xff1a;粗体由两个 * &＃xff0c;斜体由1个 * 包裹

• 实例演示

我是**粗体**
我是*斜体*


我是粗体
我是斜体

说 明 &＃xff1a; 在粗体和斜体语法标记的内部&＃xff0c;建议不要有空格。

2.1.2 段落与换行

  Markdown中的段落由一行或多行文本组成&＃xff0c;不同的段落之间使用空行来标记。

• 语法说明

1. 如果行与行之间没有空行&＃xff0c;则会被视为同一段落。
2. 如果行与行之间有空行&＃xff0c;则会被视为不同的段落。
3. 空行是指行内什么都没有&＃xff0c;或者只有空格和制表符。
4. 如果想在段内换行&＃xff0c;则需要在上一行的结尾插入两个以上的空格然后按回车键。

• 实例演示

没有空行1
没有空行2------有空行1有空行2------段内换行&＃xff0c;要有空格
而且是二个以上的空格


没有空行1
没有空行2

有空行1

有空行2

段内换行&＃xff0c;要有空格
而且是二个以上的空格

• 使用规范

为了便于阅读&＃xff0c;应该限制每行字符的数量&＃xff0c;通常每行不超过80个字符&＃xff0c;可以在编辑器中进行设置。

1. 当超过80个字符后进行换行。
2. 在一句话结束&＃xff08;。或!或?&＃xff09;之后换行。
3. 当URL较长时换行。通常URL较长会导致行字符数量超过限制&＃xff0c;为了提高可读性&＃xff0c;可以在URL之前加一个换行符。

1.列表

  在Markdown中支持使用有序列表和无序列表。

• 语法如下

  • 有序列表&＃xff1a;数字序号 &＃43; 英文句号 &＃43; 空格 &＃43; 列表内容来标记
  • 无序列表&＃xff1a; * / &＃43; / - &＃43; 空格 &＃43; 列表内容来标记。
  1. 列表中可以嵌套列表。
  2. 有序列表和无序列表也可以互相嵌套。

• 实例演示

1. 有序列表1
2. 有序列表2
3. 有序列表3
4. 有序列表4* 无序列表1
* 无序列表1
&＃43; 无序列表2
&＃43; 无序列表2
- 无序列表3
- 无序列表3


1. 有序列表1
2. 有序列表2
3. 有序列表3
4. 有序列表4

• 无序列表1
• 无序列表1

• 无序列表2
• 无序列表2

• 无序列表3
• 无序列表3

• 嵌套列表的语法

1. 有序嵌套列表12. 有序嵌套列表23. 有序嵌套列表34. 有序嵌套列表4* 无序嵌套列表1* 无序嵌套列表1* 无序嵌套列表2* 无序嵌套列表21. 有序无序嵌套列表&＃43; 有序无序嵌套列表1. 有序无序嵌套列表2. 有序无序嵌套列表&＃43; 有序无序嵌套列表


1. 有序嵌套列表1
   1. 有序嵌套列表2
      1. 有序嵌套列表3
         1. 有序嵌套列表4

• 无序嵌套列表1
  • 无序嵌套列表1
    • 无序嵌套列表2
      • 无序嵌套列表2

1. 有序无序嵌套列表
   • 有序无序嵌套列表
     1. 有序无序嵌套列表
     2. 有序无序嵌套列表
   • 有序无序嵌套列表

• 使用规范
    建议使用-来标记无序列表&＃xff0c;因为 * 容易跟粗体和斜体混淆&＃xff0c;而 &＃43; 不流行。
    如果一个列表中所有的列表项都没有换行&＃xff0c;建议使用1个空格。

- 推荐
- 推荐- 不推荐
- 不推荐


• 推荐

• 推荐

• 不推荐

• 不推荐

  如果列表项有换行&＃xff0c;则建议给无序列表使用3个空格&＃xff0c;给有序列表使用2个空格。

推荐- 这个列表项有换行- 这个没有1. 这个有序列表项有换行2. 这个没有不推荐- 这个列表项有换行
- 这个没有1. 这个有序列表项有换行
2. 这个没有


  如果一个列表中的每个列表项都只有1行&＃xff0c;建议列表项之间不要有空行。

推荐- 列表
- 列表
- 列表不推荐- 列表- 列表- 列表


  如果列表项中有换行&＃xff0c;建议在列表项之间空1行&＃xff0c;这样会比较容易区分多行列表项的开始和结束。

推荐- 列表换行- 列表- 列表不推荐- 列表换行
- 列表
- 列表


  建议在列表前/后都空1行。

推荐- 列表
- 列表
- 列表推荐这样书写不推荐
- 列表
- 列表
- 列表
推荐这样书写


  数字、字符、符号列表使用英文半角句号&＃xff0c;句号后加空格。

正确1. 我是好人
2. 他是好人
3. 你也是好人不正确1。我是好人
2、他是好人
3.你也是好人正确a. 我是好人
b. 他是好人不正确a.我是好人
b.他是好人


2.分隔线

在Markdown中&＃xff0c;分隔线由3个以上的* / - / _ 来标记。

• 使用分割线的语法

******------______


• 语法说明

**** * *******---- - -------____ _ _______


1. 分隔线须使用至少3个以上的 * / - / _ 来标记。
2. 行内不能有其他的字符。
3. 可以在标记符中间加上空格。

2.1.3 图片

• 插入图片的语法

![图片的替代的文字](图片地址)


• 语法说明

1. 图片替代文字在图片无法正常显示时会比较有用&＃xff0c;正常情况下可以为空。
2. 图片地址可以是本地图片的路径也可以是网络图片的地址。
3. 本地图片支持相对路径和绝对路径两种方式。

• 实例演示

这是本地图片与网络图片

![图片的替代的文字](../img/00022.gif)![网络图片](https://img.php1.cn/3cd4a/1eebe/cd5/086aec93f5e1e9b2.webp)


由于本地图片在CSDN上无法展示就不在书写了

2.1.4 链接

1.文字链接

  文字链接就是把链接地址直接写在文本中。语法是用方括号包裹链接文字&＃xff0c;后面紧跟着括号包裹的链接地址

• 语法格式

  [链接文字](链接地址)


• 实例演示

github官网地址在[这里](https://github.com/)


github官网地址在这里

也可以有另一种写法&＃xff0c;目的是为了防止文字与链接写在一起

github官网地址在[这里]&＃xff0c;而我最常用的还是[百度]来搜索东西&＃xff0c;或者是[天猫]来购物[这里]: https://github.com/
[百度]: https://www.baidu.com/
[天猫]: https://www.tmall.com/


github官网地址在这里&＃xff0c;而我最常用的还是百度来搜索东西&＃xff0c;或者是天猫来购物

说明&＃xff1a; 把链接地址在某个地方统一定义好&＃xff0c;然后在正文中通过“变量 ”来引用&＃xff0c;可读性一下子就变强了&＃xff0c;这种方法叫作引用链接。

2.引用链接

• 语法格式

1. 在正文中引用链接标记&＃xff0c;可以理解为引用定义好的变量
   [连接文字][链接标记]

2. 在底部定义链接标记&＃xff0c;可以理解为定义一个地址变量
   [链接标记][链接地址]

• 语法说明

1. 链接标记可以有字母、数字、空格和标点符号。
2. 链接标记不区分大小写。
3. 定义的链接内容可以放在当前文件的任意位置&＃xff0c;建议放在页尾。
4. 当链接地址为网络地址时要以 http/https开头&＃xff0c;否则会被识别为本地地址。

3.网址链接

  将网络地址或邮箱地址使用<>包裹起来会被自动转换为超链接。

• 语法格式

• 实例演示

https://www.baidu.com
myEmail&＃64;126.com

4.使用规范

  链接标题的信息应该更丰富&＃xff0c;从标题中应该可以知道链接的内容&＃xff0c;要使用有意义的链接标题。建议使用<>包裹自动链接&＃xff0c;这种方式更通用。

2.1.5 行内代码与代码块

1.行内代码

行内代码引用使用 &＃96; 包裹

• 语法格式

&＃96;代码&＃96;


• 实例演示

使用&＃96;cd ..&＃96;进入上一级命令
使用&＃96;mkdir&＃96;创建文件夹


使用cd ..进入上一级命令
使用mkdir创建文件夹

2.代码块

代码块以Tab键或4个空格开头

以tab键开头def fun():print(3&＃43;4)以四个空格开头def fun():print(3&＃43;4)


以tab键开头

def fun():print(3&＃43;4)


以四个空格开头

def fun():print(3&＃43;4)


小提示&＃xff1a; 因为代码块使用Tab键或4个空格开头的效果不够直观&＃xff0c;很多扩展语法&＃xff08;如GFM&＃xff09;提供了围栏代码块&＃xff0c;并且支持语法高亮。

3.使用规范

1. 除行内代码可以使用 &＃96; 包裹以外&＃xff0c;如果我们想转义或强调某些字符&＃xff0c;也可以使用 &＃96; 包裹。

若你想删库跑路可以执行&＃96;rm -rf /&＃96;
若你不想想删库&＃96;跑路&＃96;可以查看手册


若你想删库跑路可以执行rm -rf /
若你不想想删库跑路可以查看手册

2. 如果代码超过1行&＃xff0c;请使用围栏代码块&＃xff08;扩展语法&＃xff09;&＃xff0c;并显式地声明语言&＃xff0c;这样做便于阅读&＃xff0c;并且可以显示语法高亮。但如果我们编写的是简单的代码片段&＃xff0c;使用4个空格缩进的代码块也许更清晰。

   &＃96;&＃96;&＃96;pythondef fun():print(3&＃43;4)&＃96;&＃96;&＃96;


进入上一级命令cd ..


3. 很多Shell命令都要粘贴到终端中去执行&＃xff0c;因此最好避免在Shell命令中使用任何换行操作&＃xff1b;可以在行尾使用一个\&＃xff0c;这样既能避免命令换行&＃xff0c;又能提高源码的可读性。

   &＃96;&＃96;&＃96;shelljvs run --test&＃61;test/home/test_login.py::test_login_failed --env&＃61;online \ --username&＃61;"XXX" --password&＃61;"xxx" --url&＃61;"https://www.baidu.com"&＃96;&＃96;&＃96;


4. 建议不要在没有输出内容的Shell命令前加 $ 。在命令没有输出内容的情况下&＃xff0c; $ 是没有必要的&＃xff0c;因为内容全是命令&＃xff0c;我们不会把命令和输出的内容混淆。

5. 建议在有输出内容的Shell命令前加上$&＃xff0c;这样会比较容易区分命令和输出的内容。

2.1.6 引用

引用由 > &＃43; 引用内容来标记

• 语法说明

1. 多行引用也可以在每一行的开头都插入 > 。
2. 在引用中可以嵌套引用。
3. 在引用中可以使用其他的Markdown语法。
4. 段落与换行的格式在引用中也是适用的。

• 实例演示

引用> 引用句子多行引用> 多行引用第一行&＃xff0c;最后要有两个空格
> 多行引用第二行多行引用> 多行引用第一行> 多行引用第二行引用嵌套引用> 多行引用第一行
> > 多行引用第二行引用中使用其他Md标记> 这个是[github链接](https://github.com/)
> **加粗**和*斜体*夜之城


引用

引用句子

多行引用

多行引用第一行&＃xff0c;最后要有两个空格
多行引用第二行

多行引用

多行引用第一行

多行引用第二行

引用嵌套引用

多行引用第一行

多行引用第二行

引用中使用其他Md标记

这个是github链接
加粗和斜体夜之城

2.使用规范

1. 建议在引用的标记符号&＃xff1e;之后添加一个空格。
2. 建议每一行引用都使用符号&＃xff1e;。
3. 不要在引用中添加空行。

2.1.7 转义

  当想在Markdown文件中插入一些标记符号&＃xff0c;但又不想让这些符号被渲染时&＃xff0c;可以使用 \ 进行转义

• 语法格式

  \特殊符号


1. 可被转义的特殊符号

\ 反斜杠
&＃96; 反引号
* 星号
_ 底线
{} 花括号
[] 方括号
() 括弧
# 井字号
&＃43; 加号
- 减号
. 英文句点
! 感叹号


• 实例演示

\\
\&＃96;
\*
\_
\{\}
\[\]


\
&＃96;
*
_
{}
[]

2.2 扩展语法GFM

  在众多Markdown扩展语法中&＃xff0c;GitHub Flavored Markdown&＃xff08;简称GFM&＃xff09;无疑是目前最流行的&＃xff0c;它提供了包括表格、任务列表、删除线、围栏代码、Emoji等在内的标记语法

2.2.1 删除线

• 语法格式

~~删除的文字~~


• 实例演示

~~删除的文字~~
不支持换行删除&＃xff0c;~~我说的是真的。
你要是不信就是自己试试~~


删除的文字
支持换行删除&＃xff0c;我说的是真的。
你要是不信就是自己试试

2.2.2 表情符号

使用&＃xff1a;包裹表情代码即可

• 语法格式

  :表情代码:


• 实例演示

:boy:
:cupid:
:girl:
:unamused:


&＃x1f466;
&＃x1f498;
&＃x1f467;
&＃x1f612;

更多的表情符号请参考http://www.webpagefx.com/tools/emoji-cheat-sheet/

2.2.3 自动链接

  由 <> 包裹的URL地址被自动识别并解析为超链接&＃xff0c;使用GFM扩展语法则可以不使用 <> 包裹。

标准语法中由 <> 包裹的URL地址被自动识别并解析为超链接使用GFM扩展语法则可以不使用 <> 包裹https://www.baidu.com


注意&＃xff1a; 自动链接只识别以www或http://开头的URL地址。如果不想使用自动链接&＃xff0c;也可以使用 &＃96; 包裹URL地址如下

2.2.4 表格

• 表格的语法

  |表头1|表头2|表头3||---|---|---||内容1|内容2|内容3||内容1|内容2|内容3|


• 语法说明

1. 单元格使用|来分隔&＃xff0c;为了阅读更清晰&＃xff0c;建议最前和最后都使用|。
2. 单元格和|之间的空格会被移除。
3. 表头与其他行使用-来分隔。
4. 表格对齐格式如下。
   ○ 左对齐&＃xff08;默认&＃xff09;&＃xff1a;:
   ○ 右对齐&＃xff1a;-:
   ○ 居中对齐&＃xff1a;:-:
5. 块级元素&＃xff08;代码区块、引用区块&＃xff09;不能插入表格中。

• 实例演示

表格格式|表头1|表头2|表头3|
|---|---|---|
|内容1|内容2|内容3|
|内容1|内容2|内容3|对齐格式|左对齐|右对齐|居中对齐|
|:---|---:|:---:|
|1|github|https://github.com/|
|2|CSDN|https://mp.csdn.net/|表格内使用其他标记|序号|标题|网址|
|---|---|---|
|**1&＃xff08;加粗&＃xff09;**|github|https://github.com/|
|*2&＃xff08;斜体&＃xff09;*|CSDN|https://mp.csdn.net/|


表格格式

对齐格式

表格内使用其他标记

• 创建表格的建议

1. 在表格的前、后各空1行。
2. 在每一行最前和最后都使用|&＃xff0c;每一行中的|要尽量都对齐。
3. 不要使用庞大复杂的表格&＃xff0c;那样会难以维护和阅读。

2.2.5 任务列表

• 语法格式

- [ ] 未勾选
- [x] 已勾选


• 语法说明

1. 任务列表以 - &＃43; 空格开头&＃xff0c;由 [ &＃43; 空格 / x &＃43; ] 组成。
2. x可以小写&＃xff0c;也可以大写&＃xff0c;有些编辑器可能不支持大写&＃xff0c;所以为避免解析错误&＃xff0c;推荐使用小写的x。
3. 当方括号中的字符为空格时&＃xff0c;复选框是未选中状态&＃xff0c;为x时是选中状态。

• 实例演示

任务进度1&＃43; [x] 第一阶段
&＃43; [ ] 第二阶段
&＃43; [ ] 第三阶段任务进度详细2&＃43; [x] 第一阶段&＃43; [ ] 第1阶段&＃43; [ ] 第2阶段
&＃43; [x] 第二阶段&＃43; [x] 第1阶段&＃43; [ ] 第2阶段


任务进度1

• 第一阶段
• 第二阶段
• 第三阶段

任务进度详细2

• 第一阶段
  • 第1阶段
  • 第2阶段
• 第二阶段
  • 第1阶段
  • 第2阶段

2.2.6 围栏代码块

  在基础语法中&＃xff0c;代码块使用Tab键或4个空格开头&＃xff1b;在扩展语法中&＃xff0c;围栏代码块使用连续3个 &＃96; 或3个 ~ 包裹&＃xff0c;还支持语法高亮&＃xff0c;可读性和可维护性更强一些。

• 语法格式

  &＃96;&＃96;&＃96;代码片段&＃96;&＃96;&＃96;或者~~~代码片段~~~语法高亮&＃96;&＃96;&＃96;python代码片段&＃96;&＃96;&＃96;


• 语法说明

  围栏代码块使用连续3个&＃96;或3个~包裹&＃xff0c;支持语法高亮并可以加上编程语言的名字。

• 实例演示

  &＃96;&＃96;&＃96;def fun():pass&＃96;&＃96;&＃96;~~~def fun():pass~~~&＃96;&＃96;&＃96;pythondef fun():pass&＃96;&＃96;&＃96;~~~pythondef fun():pass~~~


def fun():pass


def fun():pass


def fun():pass


def fun():pass


建议围栏代码块被空行包裹。

2.2.7 锚点

  锚点&＃xff0c;也称为书签&＃xff0c;用来标记文档的特定位置&＃xff0c;使用锚点可以跳转到当前文档或其他文档中指定的标记位置。
  Markdown会被渲染成HTML页面&＃xff0c;在HTML页面中可以通过锚点实现跳转&＃xff1b;GitHub、GitBook项目文档中的目录也是通过锚点实现跳转的。

• 语法格式

  [锚点描述](#锚点名)


• 语法说明

1. 锚点名建议使用字母和数字&＃xff0c;当然中文也是被支持的&＃xff0c;但不排除有些网站支持得不够好。
2. 锚点名是区分英文大小写的。
3. 在锚点名中不能含有空格&＃xff0c;也不能含有特殊字符。

• 实例演示

目录[第一段](#第01段)
[第二段](#第02段)第01段 巴拉巴拉
第02段 bala bala


目录

第一段
第二段

第01段 巴拉巴拉
第02段 bala bala

注意&＃xff1a; 笔者发现以上两种似乎支持并不是很好&＃xff0c;所以建议参考别的文章来实现锚点&＃xff0c;笔者找到了CSDN的一篇参考&＃xff1a;https://blog.csdn.net/weixin_45844049/article/details/103866977

2.3 排版技巧

2.3.1 推荐的排版样式

  下面有两个比较好的排版示例&＃xff0c;注意观察它们是如何使用段落、数字、英文和标点符号的。

  上面左图是受关注比较多的技术公众号“谷歌开发者”的版面&＃xff0c;右图是付费学习平台“得到”的版面。

2.3.2 关于空格

  建议中文和英文之间加空格&＃xff0c;中文/英文和数字之间也要加空格&＃xff0c;不过有些编辑器和输入法&＃xff08;如百度输入法&＃xff09;会自动添加空隙&＃xff0c;我们就没必要手动添加了&＃xff0c;大家在使用时请多注意。

1. 一些需要加空格的情况

• 英文标点符号&＃xff08;如,.;:?&＃xff09;与后面的字符之间需要加空格&＃xff0c;与前面的字符之间不需要加空格。
• 当在中文、英文中使用&＃xff1e;&＃xff08;半角&＃xff09;标识路径时&＃xff0c;两边都需要加空格。

2. 不加空格的情况

• 中文标点符号和数字、中文、英文之间不需要添加空格。
• 数字和百分号之间不需要添加空格。
• 数字和单位符号之间不需要添加空格。
• 英文和数字组合成的名字之间不需要添加空格。
• 当 / &＃xff08;半角&＃xff09;表示“或”、“路径”时&＃xff0c;与前后的字符之间均不加空格。
• 货币符号后不加空格。
• 负号后不加空格。

2.3.3 全角和半角

全角&＃xff1a;中文标点符号是全角&＃xff0c;占两个字节。
半角&＃xff1a;英文标点符号和数字是半角&＃xff0c;占1个字节。
全角&＃xff1a;&＃xff0c;。&＃xff1b;&＃xff1a;!#
半角&＃xff1a;,.;:!#

• 在中文排版中&＃xff0c;要使用全角标点符号。
• 在英文排版中&＃xff0c;要使用半角标点符号。

2.3.4 正确的英文大小写

  很多人在文章、邮件甚至简历中&＃xff0c;会把专有名词写错&＃xff0c;虽然这并不会影响人们对内容的理解&＃xff0c;但有时的确会让人觉得你不太“专业”。专有名词要使用正确的大小写&＃xff0c;请参考它们的官方文档。

2.4 本章小结

  学完本章以后&＃xff0c;相信你已经可以使用 Markdown 写作了&＃xff0c;对于文章的排版也一定有了很多新的认识。不过要记住这么多语法规范确实不太容易&＃xff0c;还好很多编辑器&＃xff08;如Typora&＃xff09;已经帮我们规避了那些容易出错的地方&＃xff0c;VS Code也有插件能够进行语法检查。