2.1 基础语法

2.1.1 字体

1.标题

在Markdown语法中，标题支持使用两种标记：底线（-/=）和#。

· 使用底线的语法如下。

或

语法说明如下。

1）底线是=表示一级标题。

2）底线是-表示二级标题。

3）底线符号的数量至少2个。

4）这种语法只支持这两级标题。

实例演示如下。

· 使用＃的语法如下。

语法说明如下。

1）在行首插入#可标记出标题。

2）#的个数表示了标题的等级。

3）建议在#后加一个空格。

4）Markdown中最多只支持前六级标题。

实例演示如下。

· 使用规范。

建议使用#标记标题，而不是===或-，因为后者会难以阅读和维护。

推荐：

不推荐：

要保持间距，建议标题的前后都要空1行（除非标题在文档开头）；#与标题文本之间也要有1个空格，否则会导致阅读困难。

推荐：

不推荐：

不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格。

推荐：

不推荐：

建议标题的结尾不要有标点符号，如句号、逗号、冒号、分号等。

推荐：

不推荐：

建议标题要尽量简短，这样方便引用，特别是当生成目录时。如果原拟的标题是一个长句，可以从长句中提取标题，而将长句作为标题下的内容。

推荐：

不推荐：

使用Markdown写文档比较推荐的结构如下。

说明如下。

1）文档标题：文档的第一个标题应该是一级标题，写在第一行，建议与文件名相同，标题要尽量简短。

2）作者：可选，用于声明文档的作者，如果是开源项目的文档，建议把作者名写在修订历史中。

3）摘要：用1~3句话描述文档的核心内容。

4）目录：用于快速了解文档的结构，便于导航。

5）正文：正文中的标题从二级目录开始，逐级增加，不可跳级，不可相同。

2.粗体和斜体

在Markdown中，粗体由两个 * 或两个_包裹，斜体由1个 * 或1个_包裹。

· 粗体格式的语法如下。

· 斜体格式的语法如下。

· 实例演示如下。

· 使用规范。

建议粗体使用2个 * 包裹，斜体使用1个 * 包裹，因为 * 比较常见，而且比_可读性更强。

推荐：

不推荐：

在粗体和斜体语法标记的内部，建议不要有空格。

不推荐：

2.1.2 段落与换行

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

· 语法说明如下。

1）如果行与行之间没有空行，则会被视为同一段落。

2）如果行与行之间有空行，则会被视为不同的段落。

3）空行是指行内什么都没有，或者只有空格和制表符。

4）如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。

· 实例演示如下。

· 使用规范。

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

关于换行，建议如下。

1）当超过80个字符后进行换行。

2）在一句话结束（。或！或？）之后换行。

3）当URL较长时换行。

通常URL较长会导致行字符数量超过限制，为了提高可读性，可以在URL之前加一个换行符。

例如：

或者通过引用链接来进行优化：

1.列表

在Markdown中支持使用有序列表和无序列表，有序列表用数字序号+英文句号+空格+列表内容来标记，无序列表由 * /+/-+空格+列表内容来标记。

· 有序列表的语法如下。

实例演示如下。

· 无序列表的语法如下。

小提示： 使用 * /+/-来标记无序列表的效果是相同的。

实例演示如下。

· 嵌套列表的语法示例如下。

语法说明如下。

1）列表中可以嵌套列表。

2）有序列表和无序列表也可以互相嵌套。

实例演示如下。

· 使用规范。

建议使用-来标记无序列表，因为 * 容易跟粗体和斜体混淆，而+不流行。因此，推荐：

不推荐：

如果一个列表中所有的列表项都没有换行，建议使用1个空格。因此，推荐：

不推荐：

如果列表项有换行，则建议给无序列表使用3个空格，给有序列表使用2个空格。因此，推荐：

不推荐：

如果一个列表中的每个列表项都只有1行，建议列表项之间不要有空行。因此，推荐：

不推荐：

如果列表项中有换行，建议在列表项之间空1行，这样会比较容易区分多行列表项的开始和结束。因此，推荐：

不推荐：

建议在列表前/后都空1行。因此，推荐：

不推荐：

数字、字符、符号列表使用英文半角句号，句号后加空格。

示例 1.数字列表

正确：

错误：

示例2.字符列表

正确：

错误：

2.分隔线

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

· 使用分割线的语法如下。

· 语法说明如下。

1）分隔线须使用至少3个以上的 * /-/_来标记。

2）行内不能有其他的字符。

3）可以在标记符中间加上空格。

· 实例演示如下。

2.1.3 图片

· 插入图片的语法如下。

· 语法说明如下。

1）图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。

2）图片地址可以是本地图片的路径也可以是网络图片的地址。

3）本地图片支持相对路径和绝对路径两种方式。

· 实例演示如下。

2.1.4 链接

1.文字链接

文字链接就是把链接地址直接写在文本中。语法是用方括号包裹链接文字，后面紧跟着括号包裹的链接地址，如下所示。

实例演示如下。

这样的写法是没有任何问题的，但由于链接跟文字都写在了一起，如果链接过多会导致可读性差一些。

如果换一种写法呢，例如这样。

如上所示，把链接地址在某个地方统一定义好，然后在正文中通过“ 变量 ”来引用，可读性一下子就变强了，这种方法叫作引用链接。效果如下图所示。

2.引用链接

引用链接是把链接地址作为“ 变量 ”先在Markdown文件的页尾定义好，然后在正文中进行引用。其语法如下。

语法说明如下。

1）链接标记可以有字母、数字、空格和标点符号。

2）链接标记不区分大小写。

3）定义的链接内容可以放在当前文件的任意位置，建议放在页尾。

4）当链接地址为网络地址时要以 http/https开头，否则会被识别为本地地址。

3.网址链接

在Markdown中，将网络地址或邮箱地址使用<>包裹起来会被自动转换为超链接。其语法如下。

实例演示如下。

4.使用规范

在Markdown中，链接标题的信息应该更丰富，从标题中应该可以知道链接的内容，要使用有意义的链接标题。

不推荐：

推荐：

建议使用<>包裹自动链接，这种方式更通用。

推荐：

不推荐：

自动链接要以http/https开头。

推荐：

不推荐：

2.1.5 行内代码与代码块

1.行内代码

在Markdown中，行内代码引用使用`包裹，语法如下。

实例演示如下。

2.代码块

在Markdown中，代码块以Tab键或4个空格开头，语法如下。

实例演示如下。

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

3.使用规范

除行内代码可以使用`包裹以外，如果我们想转义或强调某些字符，也可以使用`包裹。

推荐：

如果代码超过1行，请使用围栏代码块（扩展语法），并显式地声明语言，这样做便于阅读，并且可以显示语法高亮。

推荐：

但如果我们编写的是简单的代码片段，使用4个空格缩进的代码块也许更清晰。

推荐：

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

推荐：

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

推荐：

不推荐：

建议在有输出内容的Shell命令前加上$，这样会比较容易区分命令和输出的内容。

推荐：

不推荐：

2.1.6 引用

1.语法

在Markdown中，引用由>+引用内容来标记，如下所示。

语法说明如下。

1）多行引用也可以在每一行的开头都插入>。

2）在引用中可以嵌套引用。

3）在引用中可以使用其他的Markdown语法。

4）段落与换行的格式在引用中也是适用的。

实例演示如下。

2.使用规范

· 建议在引用的标记符号＞之后添加一个空格。

推荐：

不推荐：

· 建议每一行引用都使用符号＞。

推荐 ：

不推荐：

· 不要在引用中添加空行。

推荐：

不推荐：

2.1.7 转义

当我们想在Markdown文件中插入一些标记符号，但又不想让这些符号被渲染时，可以使用\进行转义，语法如下。

可被转义的特殊符号如下。

实例演示如下。 jWB7d5QKfXrHTZJYlf9igh7XcmHW0UN/wnWLYJCzeJVnE7ogwUAuN6xg3+KMFJXB