Markdown 小结

Markdown 是一种轻量级标记语言，它允许人们使用易读、易写的纯文本格式编写文档。Markdown 语言需要经过编辑器的渲染才能呈现出各种优美的格式。

Markdown 的使用场景：

当你对文章的排版没什么特殊需求，且不想花太多时间在排版上时，就可以使用 Markdown。因为编辑器或平台会通过 Markdown 标记对文章进行渲染，最终的排版效果会非常简洁、漂亮。

Markdown 标题：

标题推荐语法：

# + 空格 + 标题内容

语法说明如下：

• 在行首插入 # 可标记出标题。
• # 的个数表示了标题的等级。
• 建议在 # 后加一个空格。
• Markdown 中最多只支持前六级标题，类似于 HTML 中的 h1~h6。

标题规范如下：

1) 建议使用#标记标题，而不是 === 或 ---
2) 要保持间距，建议标题的前后都要空 1 行（除非标题在文档开头）；# 与标题文本之间也要有1个空格
3) 不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格。
4) 建议标题的结尾不要有标点符号，如句号、逗号、冒号、分号等。
5) 建议标题要尽量简短，这样方便引用，特别是当生成目录时。如果原拟的标题是一个长句，可以从长句中提取标题，而将长句作为标题下的内容。

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

# 文档标题

作者

摘要

目录

## 标题1

### 标题 1.1

## 标题2

### 标题2.1

### 标题2.2

说明如下：

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

Markdown 加粗和斜体：

在 Markdown 中，加粗（粗体）由两个 * 或两个 _ 包裹，斜体由一个 * 或一个 _ 包裹。

示例：

**加粗**
__加粗__

*斜体*
_斜体_

加粗 和 斜体 的使用规范：

1) 建议粗体使用两个*包裹，斜体使用一个*包裹，因为*比较常见，而且比_可读性更强。
2) 在粗体和斜体语法标记的内部，建议不要有空格。

Markdown 的段落和换行：

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

语法说明如下：

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

示例如下：

段落和换行的规范：

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

关于换行，建议如下：

• 当超过80个字符后进行换行。
• 在一句话结束（句号、叹号或问号）之后换行。
• 当 URL 较长时换行。

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

大家好，给大家推荐一套不错的 Python 教程：
[Python基础教程，Python入门教程（非常详细）](http://c.biancheng.net/python/)

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

大家好，给大家推荐一套不错的 Python 教程：[Python基础教程，Python入门教程（非常详细）]

[Python基础教程，Python入门教程（非常详细）]: http://c.biancheng.net/python/

Markdown列表：

Markdown 支持使用有序列表和无序列表，类似于 HTML 中的 <ul> 和 <ol> 标签。

有序列表的语法如下：

数字序号 + 英文句号 + 空格 + 列表内容

无序列表的语法如下：

*/+/-  +  空格  +  列表内容

使用*、+、-来标记无序列表的效果是相同的。

列表的嵌套：

嵌套列表的语法：

+ 第一层列表
TAB + 第二层列表
TAB + TAB + 第三层列表

语法说明如下。

• 列表中可以嵌套列表。
• 有序列表和无序列表也可以互相嵌套。

列表使用规范：

1) 建议使用 - 来标记无序列表，因为*容易跟粗体和斜体混淆，而+不流行。
2) 如果一个列表中所有的列表项都没有换行，建议使用 1 个空格。 （列表项内容和列表标识之间）
3) 如果列表项有换行，则建议给无序列表使用 3 个空格，给有序列表使用 2 个空格。（列表项内容和列表标识之间）
4) 如果一个列表中的每个列表项都只有 1 行，建议列表项之间不要有空行。
5) 如果列表项中有换行，建议在列表项之间空 1 行，这样会比较容易区分多行列表项的开始和结束。
6) 建议在列表前/后都空 1 行。

示例如下：

# 列表

## 有序列表

1. C语言中文网
2. Markdown教程
3. http://c.biancheng.net/markdown/

## 无序列表

- 使用【减号】标识无序列表
- 使用【减号】标识无序列表

## 嵌套列表

- 我是第一层列表
    - 我是第二层列表
        - 我是第三层列表
            - 我是第四层列表

## 有序列表和无序列表相互嵌套

1. 我是第一层列表
    - 我是第二层列表
        1. 我是第三层列表一
        2. 我是第三层列表二

- C语言入门教程
- http://c.biancheng.net/c/

-   C语言入门教程
-   http://c.biancheng.net/c/

-   这个列表
    有换行
-   这个没有换行

1.  这个有序列表
    有换行
2.  这个没有换行

- Markdown教程：http://c.biancheng.net/markdown/
- Python教程：http://c.biancheng.net/python/
- Java教程：http://c.biancheng.net/java/

-   Markdown教程：
    http://c.biancheng.net/markdown/

-   Python教程：
    http://c.biancheng.net/python/

-   Java教程：
    http://c.biancheng.net/java/

markdown 下划线：

在 Markdown 中，分隔线由 3 个以上的*或者_来标记。_是下划线，而不是减号。

语法如下：

第一行内容
***
第二行内容
___
第三行内容

语法说明：

• 分隔线须使用至少 3 个以上的*或者_来标记。
• 标识符行内不能有其他的字符。
• 可以在标记符中间加上空格。

示例如下：

## 星号作为分割线

第一行内容
***
第二行内容  
哈哈
* * * 
第三行内容
********

## 下划线作为分割线

第一行内容
___
第二行内容
_ _ _
第三行内容
_______

markdown插入图片：

语法：

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

语法说明如下：

• 图片替代文字在图片无法正常显示时会比较有用，类似于 HTML <img> 标签的 alt 属性，正常情况下可以为空。
• 图片地址可以是本地图片的路径也可以是网络图片的地址。
• 本地图片支持相对路径和绝对路径两种方式。(mac 中，/ 表示markdown 同级目录)

 示例如下：

### 本地图片： 无文字替代图片

![](/avatar.jpg)

### 本地图片： 有文字替代图片

![我的头像](avatar.jpg)

### 网络图片

![C语言中文网logo](http://c.biancheng.net/uploads/allimg/191121/logo.png)

markdown 超链接：

Markdown 支持插入三种链接，分别是：文字链接、引用链接和网址链接。

1. 文字链接：

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

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

示例：

## 文字链接

编程教程有：[C语言入门教程](http://c.biancheng.net/c/)、[从C语言到C++](http://c.biancheng.net/cplus/)、[Python教程](http://c.biancheng.net/python/)等

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

2. 引用链接：

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

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

首先定义好链接标记，可以理解为编程语言中的定义变量：

[链接标记]: 链接地址

然后在正文中引用定义好的链接标记，可以理解为引用定义好的变量：

[链接文字][链接标记]

使用链接时，可以只写“链接标记”而不写“链接文字”。只有“链接标记”时会给“链接标记”加链接，两者同时出现时给“链接文字”加链接。

其它注意事项：

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

示例：

## 引用链接

## 只写链接标记

常用的编程语言有：[C语言]、[C++]和[Python]等。

## 同时写链接标记和链接文字

编程语言有：[C语言入门教程][C语言]、[C++从入门到放弃][C++]、[Python教程][python]

[C语言]:http://c.biancheng.net/c/
[C++]:http://c.biancheng.net/cplus/
[python]:http://c.biancheng.net/python/

3. 网址链接：

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

<URL 或者 Email>

示例：

## 网址链接

<http://c.biancheng.net/markdown/>

<andrewzheng@sina.cn>

markdown 代码：

对于编程语言的代码，Markdown 支持代码块和行内代码两种形式。

1. 代码块：

在 Markdown 中，代码块以 Tab 键或 4 个空格开头，如下所示：

## 代码块

以 Tab 键 开头

    def hello_wordl():
        print("hello world")

以 4个空格开头

    def hello_wordl():
        print("hello world")

2. 行内代码：

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

`代码`

示例如下：

## 行内代码

使用 `cd ..` 命令切换到上一级目录

使用 `mkdir 文件夹` 命令创建文件夹

3. 语法高亮：

Markdown 语法高亮是一种扩展语法，它的格式如下：

```language
code
```

其中，language 表示使用的编程语言，code 表示输入的代码。

示例如下：

## 语法高亮

```python
def hello_world():
    print("hello world")
```

使用规范：

1) 除行内代码可以使用` `包裹以外，如果我们想转义或强调某些字符，也可以使用` `包裹。
2) 如果代码超过 1 行，请使用围栏代码块（扩展语法），并显式地声明语言，这样做便于阅读，并且可以显示语法高亮。
3) 但如果我们编写的是简单的代码片段，使用 4 个空格缩进的代码块也许更清晰。
4) 很多 Shell 命令都要粘贴到终端中去执行，因此最好避免在 Shell 命令中使用任何换行操作；可以在行尾使用一个，这样既能避免命令换行，又能提高源码的可读性。
5) 建议不要在没有输出内容的 Shell 命令前加$。在命令没有输出内容的情况下，$是没有必要的，因为内容全是命令，我们不会把命令和输出的内容混淆； 建议在有输出内容的 Shell 命令前加上$，这样会比较容易区分命令和输出的内容。

markdown 引用：

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

> 引用内容

语法说明如下：

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

示例如下：

## 引用

> 我是引用的句子，请在我前面加上 >

正常的句子是这样的。

## 多行引用（写法1）

> 这是多行引用的第一行，我的最后有两个空格。  
这是多行引用的第二行

## 多行引用（写法2）

> 这是多行引用的第一行（最后有两个空格）  
> 这是多行引用中的第二行

## 引用中嵌套引用

> 引用中是可以嵌套引用的
>> 我是引用中嵌套的引用

## 引用中使用其他 Markdown 标记

> 猛击这里阅读[Markdown教程](http://c.biancheng.net/markdown/)  
> **加粗**和*斜体*也是支持的

引用的使用规范：

1) 建议在引用的标记符号>之后添加一个空格。
2) 建议每一行引用都使用符号>，并在上一行的最后添加两个空格以换行。
3) 不要在引用中添加空行。

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