程序员的文档方式：markdown快速上手

Posted 2021-10-20 顺元啊

1.前言

没使用markdown之前，开发文档都是使用doc文档。然而doc文档不利于上传到gitHub或者gitee等代码托管平台，不易查看修改记录。而markdown她简单易上手，没有繁琐的格式和排版，且很方便查看修改记录。因此，markdown成为了众多开发者的首先。相信，大家都会使用她了，因此，这里只是做个简单的介绍，记录一下我们的开发好帮手！

2.优势

1. 和doc相比，简单易上手，没有繁琐的格式和排版
2. 方便上传gitHub或gitee，易于查看修改记录
3. 很容易生成pdf或者html文档，便于转换
4. 很多网站均支持markdown写文章，因为没有格式和排版的问题，方便多平台发布

3.下载途径

支持markdown的软件和平台很多，作为平时开发文档的书写，我常常使用的开源的typora，她是我最喜欢的markdown软件了，没有之一。当然，如果你喜欢vscode，也可以通过vscode安装其插件。这里主要给出typora的下载方式：

3.1 windows安装

1. 可以通过官网地址下载：https://typora.io/
2. 或者使用chocolatey下载安装，这种基于windows包管理器的安装方式，我比较喜欢

3.2 linux安装

for Linux
# or run:
# sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BA300B7755AFCFAE
wget -qO - https://typora.io/linux/public-key.asc | sudo apt-key add -
# add Typora's repository
sudo add-apt-repository 'deb https://typora.io/linux ./'
sudo apt-get update
# install typora
sudo apt-get install typora

4. 常用命令与显示效果

4.1 分段与分行

以一个或多个空行来隔开段落；以两个或多个空格来段内换行。

4.2 标题

# This is an H1
## This is an H2
######  This is an H6

效果：

This is an H1

This is an H2

This is an H6

4.3 引用

在每一行前面写一个>：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

效果：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

或者在每一段前面写一个>：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

多重引用

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

效果：

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

列表

列表项占一行，以*、+、-开头即可：

*   Red
*   Green
*   Blue

效果：

• Red
• Green
• Blue

有序列表只需要将上述标记符换成数字加句点。而且顺序由书写顺序决定，与数字无关，但数字需要从1开始。例如：

1.  Bird
2.  McHale
3.  Parish

效果：

1. Bird
2. McHale
3. Parish

每一个列表项可以多行：

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

效果：

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

代码块

This is a normal paragraph:

```

This is a code block.

```

效果：

This is a normal paragraph:

This is a code block.

横线

三个或更多个*、-（它们之间可以有空格）会产生横线：

* * *

效果：

---

链接

内嵌链接：

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

效果：

I get 10 times more traffic from Google than from Yahoo or MSN.

如果直接以链接地址作为链接文本，可以用如下快捷写法：

[OneOS-Lite](https://gitee.com/cmcc-oneos/OneOS-Lite) 
效果：

OneOS-Lite

强调

单个*或_产生斜体，两个（**、__）则产生粗体。例如：

*like* _this_

**like** **this**

效果：

like this

like this

内嵌代码

code: `echo hello`

效果：

code: echo hello

图片

图片与链接类似，只需在文本前面加上感叹号!即可。图片位置和大小无法通过Markdown来指定。

转义字符

以下特殊字符需要用\\转义得到。

\\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

5.关注&&联系

gitee： https://gitee.com/cmcc-oneos/OneOS-Lite

docs： https://oneos-lite.com/

公众号：CMCC-OneOS