Markdown 的「简单使用」&「写作规范」
前言
本文记录了 Markdown 的「简单使用方法」和「编写规范」，希望对刚使用 Markdown 的小伙伴有帮助。
Markdown 介绍
Markdown是一种「轻量级标记语言」，创始人为约翰·格鲁伯。它允许人们使用「易读易写」的纯文本格式编写文档。Markdown编写的文档可以导出XHTML、HTML、Word、PDF、Epub等多种格式的文档。Markdown编写的文档后缀为.md，.markdown。Markdown吸收了很多在电子邮件中已有的纯文本标记的特性。- 由于
Markdown的「轻量化」「易读易写」特性，并且对于图片，图表、数学式都有支持，目前许多网站都广泛使用Markdown来撰写帮助文档或是用于论坛上发表消息。 Markdown的语法全由一些符号所组成，这些符号经过精挑细选，其作用一目了然。
Markdown 简单使用
标题
Markdown 标题有两种格式：
- 使用
=和-标记一级和二级标题(Setext形式)
=和-标记语法格式如下：
一级标题
==============
二级标题
--------------
显示的效果如下：
- 使用
#号标记(atx形式)
使用#号可表示1-6级标题，一级标题对应一个#号，二级标题对应两个#号，以此类推。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
显示的效果如下：
段落
Markdown 段落的换行是使用两个以上的空格加上回车，当然也可以在段落后面使用一个空行表示重新开始一个段落。
当然，现在有些 Markdown 编辑器直接按回车换行即可。
字体
- 斜体
在文字前后各加一个*就👌了。
*斜体*效果为：斜体
*斜体*
- 粗体
在文字前后各加**就👌了。
**粗体**效果为：粗体
**粗体**
- 斜粗体
在文字前后各加***就👌了。
***斜粗体***效果为：斜粗体
***斜粗体***
- 删除线
在文字前后各加~~就👌了。
~~删除线~~效果为：删除线
~~删除线~~
- 分割线
在一行中使用三个以上的星号*、减号-、底线_来建立一个分割线。行内不能有其他东西，但可以在星号或是减号中插入空格。
以下的写法均可以建立分割线。
***
* * *
---
- - -
___
_ _ _
- 空格
方法1：手动输入
方法2：使用「全角空格」，即在全角输入状态下使用空格即可。
方法3：输出tab空格： 
- 下滑线
下划线可以通过HTML的<u>标签来实现：
<u>带下划线的文本</u>
- 脚注
脚注的格式如下：
先写这个：这是[^要注明的文本]
最后加这个：
[^要注明的文本]: 这是脚注
列表
Markdown 支持「有序列表」和「无序列表」。
- 无序列表
无序列表使用星号*、加号+或是减号-作为列表标记，这些标记后要添加一个空格，然后填写内容。
* 第一项
* 第二项
* 第三项
+ 第一项
+ 第二项
+ 第三项
- 第一项
- 第二项
- 第三项
显示结果如下：
- 有序列表
有序列表使用数字并加上.号来表示，后面要添加一个空格，如：
1. 第一项
2. 第二项
3. 第三项
- 列表嵌套
列表嵌套只需在子列表中的选项前面添加四个空格，再使用列表符号即可，如：
1. 第一项
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
2. 第二项
- 第二项嵌套的第一个元素
- 第二项嵌套的第二个元素
区块引用
Markdown 区块引用是在段落开头使用 > 符号， 然后后面添加一个空格符号：
> 区块引用
显示结果如下：
区块引用
区块是可以嵌套的，一个 > 是最外层，然后每加一个 > 就多一层嵌套，如：
> 最外层
> > 第一层嵌套
> > > 第二层嵌套
显示结果如下：
最外层
第一层嵌套
第二层嵌套
区块中使用列表：
> 区块中使用列表
> * 第一项
> * 第二项
> * 第三项
显示结果如下：
区块中使用列表
- 第一项
- 第二项
- 第三项
列表中使用区块，需要在 > 前添加四个空格。
* 第一项
> 区块1
* 第二项
> 区块2
显示结果如下：
- 第一项
区块1
- 第二项
区块2
代码
如果只是一个片段的代码，或者有一些关键性的名词，可以用反引号(`)把它包起来，如：
`Markdown` 函数
显示结果如下：Markdown函数
代码区块使用4个空格或者一个制表符。
cout << "hello world !";
cout << endl;
显示结果如下：
cout << "hello world !";
cout << endl;
也可以用 ```包裹一段代码，并指定一种语言(可以不指定)。
显示的结果如下：
cout << "hello world !";
cout << endl;
如何在代码框中输入 ```：
````
```
cout << endl;
```
````
显示的结果如下：
```
cout << endl;
```
常见的可以指定的语言如下：
| 名称 | 关键字 |
|---|---|
| shell | bash, shell |
| C | cpp, c |
| C# | c#, c-sharp, csharp |
| CSS | css |
| Java | java |
| JavaScript | js, jscript, javascript |
| PHP | php |
| text | text, plain |
| Python | py, python |
| Ruby | ruby, rails, ror, rb |
| SQL | sql |
| Viasul Basic | vb, vbnet |
| XML | xml, xhtml, xslt, html |
| R | r, s, splus |
| matlab | matlab |
| swift | swift |
| GO | go, golang |
如果想看更多的可以参考下面的链接：
https://www.jianshu.com/p/c2b75ff24c33
https://blog.csdn.net/u012102104/article/details/78950290
链接
链接的使用方法如下：
[链接名称](链接地址)
或者
<链接地址>
高级链接暂时未用到，就不作介绍了。
图片
图片的语法格式如下：
我们插入图片时，直接从编辑器中导入即可。
表格
Markdown 制作表格使用 | 来分隔不同的单元格，用 - 来分隔表头和其他行。
语法格式如：
| 表头1 | 表头2 |
| :----: | :----: |
| 单元格1 | 单元格2 |
| 单元格3 | 单元格4 |
显示结果如下：
| 表头1 | 表头2 |
|---|---|
| 单元格1 | 单元格2 |
| 单元格3 | 单元格4 |
我们可以设置表格的对齐方式：
-:设置内容和标题栏「居右对齐」。:-设置内容和标题栏「居左对齐」。:-:设置内容和标题栏「居中对齐」。
实例代码如：
| 左对齐 | 右对齐 | 居中对齐 |
| :-----| ----: | :----: |
| 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 |
显示结果如下：
| 左对齐 | 右对齐 | 居中对齐 |
|---|---|---|
| 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 |
HTML元素
目前支持的HTML元素有：
<kbd>、<b>、<i>、<em>、<sup>、<sub>、<br> 等等。
转义
Markdown 使用了很多特殊符号来表示特定的意义，如果需要显示特定的符号，则需要使用转义字符反斜杠 /。
如：\*\*正常符号\*\*的效果为：**正常符号**。
Markdown支持以下符号前面加上反斜杠来帮助插入普通的符号：
| 符号 | 名称 |
|---|---|
| \ | 反斜杠 |
| ` | 反引号 |
| * | 星号 |
| _ | 下划线 |
| {} | 花括号 |
| [] | 方括号 |
| () | 小括号 |
| # | 井字号 |
| + | 加号 |
| - | 减号 |
| . | 英文句点 |
| ! | 感叹号 |
公式
当你需要在编辑器中插入数学公式时，可以适用两个美元符 $$ 包裹 Tex 或 LaTex 格式的数学公式来实现。
提交后，会根据需要加载 Mathjax 对数学公式进行渲染，如：
$$
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix}
\mathbf{i} & \mathbf{j} & \mathbf{k} \\
\frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\
\frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\
\end{vmatrix}
{(x+1)(x+1)}
$$
显示效果如下：
V
1
×
V
2
=
∣
i
j
k
∂
X
∂
u
∂
Y
∂
u
0
∂
X
∂
v
∂
Y
∂
v
0
∣
(
x
+
1
)
(
x
+
1
)
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix} \mathbf{i} & \mathbf{j} & \mathbf{k} \\ \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\ \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\ \end{vmatrix} {(x+1)(x+1)}
V1×V2=∣∣∣∣∣∣i∂u∂X∂v∂Xj∂u∂Y∂v∂Yk00∣∣∣∣∣∣(x+1)(x+1)
流程图
在 Markdown 中用 mermaid、flow 和 sequence等等来画流程图。
mermaid 支持三种图形的绘制，分别是「流程图」、「时序图」和「甘特图」。
流程图的方向：
graph TB：从上到下graph BT：从下到上graph RL：从右到左graph LR：从左到右graph TD：从上到下
基本图形：
id[XX]：矩形id(XX)：圆角矩形id>XX]：不对称矩形id{XX}：菱形id((XX))：圆形
节点之间的连接：
A --> B：A 带箭头指向 BA --- B：A 不带箭头指向 BA -.- B：A 用虚线指向 BA -.-> B：A 用带箭头的虚线指向 BA ==> B：A 用加粗的箭头指向 BA -- 描述 --- B：A 不带箭头指向 B，且在中间加上文字描述A -- 描述 --> B：A 带箭头指向 B，且在中间加上文字描述A -. 描述 .-> B：A 用带箭头的虚线指向 B，且在中间加上文字描述A == 描述 ==> B：A 用加粗的箭头指向 B，且在中间加上文字描述
以下的示例在 Typora 中进行。
示例代码1：
graph LR
A[方形] -->B(圆角)
B --> C{条件a}
C -->|a=1| D[结果1]
C -->|a=2| E[结果2]
F[横向流程图]
效果：
示例代码2：
graph TD
A[方形] --> B(圆角)
B --> C{条件a}
C --> |a=1| D[结果1]
C --> |a=2| E[结果2]
F[竖向流程图]
效果：
flow 教程：
https://www.cnblogs.com/Cherry-Linux/p/7797795.html
sequence 教程：
https://www.jianshu.com/p/70e329dd4a00
Markdown 写作规范
创建文件
- 后缀
「必须」使用.md。 - 文件名
「必须」使用小写，多个单词之间使用-分隔。 - 文件名
「不能」含有空格，「必须」使用半角字符。 - 文件编码
「必须」用UTF-8。 - 某些说明文件的文件名，可以使用大写字母，如
README、LICENSE。
标题
- 文档标题
「应该」这样写：
文档标题
================
- 章节标题
「必须」以##开始，而不是#。 - 章节标题
「必须」在#号后加一个空格，且后面没有#。
## 章节
// bad
#章节
##章节
## 章节 ##
- 章节标题和内容间
「必须」有一个空行。
## 章节1
内容
- 一级标题下，
「不能」直接出现三级标题
下面示例中，缺少二级标题：
# 一级标题
### 三级标题
- 标题要
「避免」同级标题只有一个。
下面示例中，二级标题 A 只包含一个三级标题，完全可以省略。
## 二级标题 A
### 三级标题 A
## 二级标题 B
- 下级标题
「尽量」不重复上级标题名字。
下面示例中，二级标题与下属的三级标题同名，建议避免。
## 概述
### 概述
「尽量」避免出现四级标题，保持层级的简单。如果三级标题下有并列性的内容，「建议」使用项目列表。
### 三级标题
1. A
2. B
3. C
中英文混排文本规则
「应该」 采用如下规则：
英文和数字使用半角符号。中文之间不加空格。中文与英文、阿拉伯数字及@#$%^&*.()等符号之间加空格。中文标点之间不加空格。中文标点与前后字符（无论全角或半角）之间不加空格。- 如果括号内有中文，则使用
中文括号。 - 如果括号中的内容全部都是英文，则使用
半角英文括号。 - 当半角符号
/表示「或者」意思时，与前后的字符之间均不加空格。 半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。英文单位与单位前的阿拉伯数字不留空格。
符号使用
「应该」采用如下规则：
- 使用直角引号
「」代替双引号“”，使用『』代替单引号‘’。 - 省略号使用
......，而。。。仅用于表示停顿。 - 句子末尾用括号加注时，句号
。应该在括号之外。 - 逗号
，表示句子内部的一般性停顿。 - 句子内部的并列词，
「应该」用全角顿号、分割，而「不用」逗号,。 - 英文句子中，并列词语之间使用半角逗号
,分割。 - 全角冒号
：常用在需要解释的词语后边，引出解释和说明。 - 表示时间时，应该使用半角符号
:。 - 应该使用平静的语气叙述，尽量避免使用感叹号
!。 - 表示两个名词的复合或图表编号时，使用直线连接号
-。
例如：
氧化-还原反应
图 1-1
- 表示数值范围（例如日期、时间或数字）时，使用波浪连接号
~，波浪连接号前后两个值都要加上单位，波浪连接号也可以用至代替。
例如：
2018年~2020年
代码
- 代码段
「必须」使用Fenced code blocks风格：
https://python-markdown.github.io/extensions/fenced_code_blocks/
示例如下：
```
cout << "hello world !" << endl;
```
表格
- 表格的写法
「应该」参考GFM：
https://docs.github.com/en/free-pro-team@latest/github/writing-on-github
示例如下：
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
| Left-Aligned | Center Aligned | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is | some wordy text | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
数值
- 数字一律使用
全角形式。 - 数值为千位以上，应该添加千分号
,（半角逗号）。
这件商品的价格为 RMB1,000,000。
- 货币应为阿拉伯数字，并在数字前写出货币符号，或者在数字后写出货币中文名称。
$1,000
1,000 美元
- 表示数值范围时，用
~连接。
变化程度的表示
- 数字的增加要使用
增加了、增加到。增加了表示增量，增加到表示定量。 - 数字的减少要使用
降低了、降低到。降低了表示增量，降低到表示定量。 「不能」用「降低N倍」或「减少N倍」的表示法，要用「降低百分之几」或「减少百分之几」。
引用
- 引用第三方内容时，应注明出处。
- 使用外部图片时，必须在图片下方或文末标明来源。
本文部分图片来自 Wikipedia
句子
「避免」使用长句。句子内部不使用逗号时，总长度不应该超过 40 个字；使用逗号时，总长度不应该超过 100 字或者正文的 3 行。「尽量」使用简单句和并列句，避免使用复合句。
写作风格
「尽量」不使用被动语态，改为使用主动语态。- 用对「的」、「地」和「得」。
- 使用代词，必须明确指代的内容，保证只有一个含义。
「避免」使用双重否定句。
更加详细的规范可以参考以下博客：
https://www.jianshu.com/p/3b638180e42c, by Victor_Xu
https://www.jianshu.com/p/84481d344a3f, by HARRISKING
Markdown 编辑器推荐
- Typora编辑器：https://typora.io/（支持
MacOS、Windows、Linux平台） - MacDown编辑器：https://macdown.uranusjr.com（支持
MacOS）
参考资料
-
菜鸟教程-Markdown教程, by 菜鸟教程(runoob.com)
-
简书上使用Markdown(超详细), by 水清_木秀
-
技术文档写作规范(Markdown), by Victor_Xu
-
Markdown 编写规范, by HARRISKING
-
简书修改图片大小, by 简子逍
-
Markdown 语法说明 (简体中文版), by Wow!Ubuntu
-
Markdown: Basics(快速入门), by Wow!Ubuntu
-
Markdown, by 维基百科
-
Markdown代码高亮支持的语言, by码农吉小星
-
Markdown代码块支持的语言, by oopp8
-
如何在Markdown中画流程图, by lkkwxy
版权声明：本文为晨旭OvO原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/a1228136188/article/details/109254188
427
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
