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