使用 Markdown 编写文档

创建时间 2020-12-29

更新时间 2020-12-29

分类

计算机技术

标签

Markdown

如你所知，这篇文章就是用 Markdown 来写的，然后在后端使用 Python 渲染成 HTML，呈现在了你的面前。所以用 Markdown 可以极大的提高写作效率，摒弃好多花里胡哨的格式困扰。我想用过 word 的话，一定会为格式产生过纠结。

基础语法

标题

下面是标题的写法，直接用 # 开头的行都认为是标题，有几个就是第几级；

# 第一级标题

## 第二级标题

### 第三级标题

#### 第四级标题

##### 第五级标题

###### 第六级标题

与 HTML 一样 Markdown 支持六级标题，不过一般来说用不了那么多。关于标题的内容我就不在这里渲染了，否则左侧的目录可能会很难看。文章中的标题应该可以很好的展示标题的样子了。

另外标题还有另一种写法，不过不常用，写法如下，在文字下面加上减号，或者等号。

第一级标题
========

第二级标题
--------

段落

随便写一行字，就是一个段落，这个不在赘述。不过有一些约束，在下文中可以看到。

换行

如果想要单独换行，在段落末尾加上两个以上的空格，然后回车，如下所示：

这里是第一行  
这里是第二行

这里是第三行 
这里是第四行

这里是第一行
这里是第二行

这里是第三行
这里是第四行

加粗

加粗可以使用 ** 或者 __ 在需要加粗的文字两侧，如下所示：

这里是 **加粗** 文字  
这里是另一个 __加粗__ 文字

这里是加粗文字
这里是另一个加粗文字

斜体

加粗可以使用 * 或者 _ 在需要加粗的文字两侧，如下所示：

这里是 *斜体* 文字  
这里是另一个 _斜体_ 文字

这里是斜体文字
这里是另一个斜体文字

加粗的斜体

加粗可以使用 *** 或者 ___ 在需要加粗的文字两侧，如下所示：

这里是 ***加粗斜体*** 文字  
这里是另一个 ___加粗斜体___ 文字

这里是 加粗斜体 文字
这里是另一个 加粗斜体 文字

引用块

在段落的开头加上 > 就变成了引用块，如下所示：

> 这里是一个引用块

这里是一个引用块

多行引用块

> 这里是一个引用块
>
> 这里是零一行

这里是一个引用块

这里是零一行

嵌套引用块

> 这里是一个引用块
>
>> 这里是嵌套的引用块

这里是一个引用块

这里是嵌套的引用块

另外，引用块可以和其他的格式组合使用。

有序列表

有需列表可以使用序号和 . 在段落前面，如下所示：

1. 第一个条目
   1. 第一个嵌套条目
   2. 第二个嵌套条目
2. 第二个条目
   1. 第一个嵌套条目
   2. 第二个嵌套条目
3. 第三个条目
   1. 第一个嵌套条目
   2. 第二个嵌套条目

第一个条目
第一个嵌套条目
第二个嵌套条目
第二个条目
第一个嵌套条目
第二个嵌套条目
第三个条目
第一个嵌套条目
第二个嵌套条目

无序列表

无需列表可以使用 -，*，+ 在段落前面，如下所示：

- 第一个减号条目
    - 第一个嵌套减号条目
    - 第二个嵌套减号条目
- 第二个减号条目
    - 第一个嵌套减号条目
    - 第二个嵌套减号条目
- 第三个减号条目
    - 第一个嵌套减号条目
    - 第二个嵌套减号条目

* 第一个星号条目
    * 第一个嵌套星号条目
    * 第二个嵌套星号条目
* 第二个星号条目
    * 第一个嵌套星号条目
    * 第二个嵌套星号条目
* 第三个星号条目
    * 第一个嵌套星号条目
    * 第二个嵌套星号条目

+ 第一个加号条目
    + 第一个嵌套加号条目
    + 第二个嵌套加号条目
+ 第二个加号条目
    + 第一个嵌套加号条目
    + 第二个嵌套加号条目
+ 第三个加号条目
    + 第一个嵌套加号条目
    + 第二个嵌套加号条目

第一个减号条目
- 第一个嵌套减号条目
- 第二个嵌套减号条目
第二个减号条目
- 第一个嵌套减号条目
- 第二个嵌套减号条目
第三个减号条目
- 第一个嵌套减号条目
- 第二个嵌套减号条目
第一个星号条目
- 第一个嵌套星号条目
- 第二个嵌套星号条目
第二个星号条目
- 第一个嵌套星号条目
- 第二个嵌套星号条目
第三个星号条目
- 第一个嵌套星号条目
- 第二个嵌套星号条目
第一个加号条目
- 第一个嵌套加号条目
- 第二个嵌套加号条目
第二个加号条目
- 第一个嵌套加号条目
- 第二个嵌套加号条目
第三个加号条目
- 第一个嵌套加号条目
- 第二个嵌套加号条目

另外，在列表中，添加段落，需要手动缩进。

任务列表

- [ ] 第一个任务条目
    + [ ] 第一个嵌套任务条目
    + [ ] 第二个嵌套任务条目
- [x] 第二个任务条目 已完成
    + [ ] 第一个嵌套任务条目
    + [ ] 第二个嵌套任务条目
- [ ] 第三个任务条目
    + [ ] 第一个嵌套任务条目
    + [ ] 第二个嵌套任务条目

代码块

可以直接使用一个反引号 ` 在代码的两侧，如下所示：

这里是一个 `print()` 函数

这里是一个 print() 函数

代码可以直接使用缩进开始，表示代码块，如下所示：

    print('hello world')

print('hello world')

或者使用三个反引号 ` 来包裹代码，后面跟上代码的类型，以支持代码高亮，如下所示：


#include &lt;iostrem&gt;

int main()
{
    std::out << "hello world!!!" << std::endl;
    return 0;
}

#include <iostrem>

int main()
{
    std::out << "hello world!!!" << std::endl;
    return 0;
}

删除线

加粗可以使用 ~~ 在需要加粗的文字两侧，如下所示：

这里是一行 ~~删除~~ 线

这里是一行删除线

水平分割线

使用三个以上的 - 就可作为水平分割线，如下所示

---

表格

| 左对齐标题   | 右对齐标题 | 居中对齐标题 |
| :----------- | ---------: | :----------: |
| 短文本       |   中等文本 | 长一点的文本 |
| 长一点的文本 |     短文本 |   中等文本   |

左对齐标题	右对齐标题	居中对齐标题
短文本	中等文本	长一点的文本
长一点的文本	短文本	中等文本

注：可以使用 | 来转义管道符号 |

链接

这里是 [百度](https://www.baidu.com) 的一个链接

这里是百度的一个链接

URL和邮件地址

<https://www.baidu.com>

<kangweibaby@163.com>

https://www.baidu.com

kangweibaby@163.com

图片

![这里是一张图片](../../../tests/static/test-001.png)

这里是一张图片

图片链接

[![这里是图片链接](../../../tests/static/test-001.png)
](https://www.sqlalchemy.org/)

HTML

Markdown 支持直接嵌入HTML.

转义字符

\
`
*
_
{}
[]
<>
()
#
+
-
.
!
|

其他 Markdown 特性

参见 https://www.markdownguide.org

参考资料

https://www.markdownguide.org