Markdown 风格指南
目录:
标题
使用 ATX 风格的标题(1~6 个 #
号)
👍:
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
👎:
一级标题
=======
最后一个 #
后空一格,标题前后空一行
👍:
前一个段落的内容……
## 一个标题
下一个段落……
👎:
##一个标题
段落内容……
一篇文章中只应有一个一级标题
👍:
# 一个一级标题
## 第一个二级标题
Blahblah……
## 第二个二级标题
Blahblah……
👎:
# 一个一级标题
## 第一个二级标题
Blahblah……
# 又一个一级标题
Blahblah……
段落
段落开头顶格
👍:
这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。
这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。
This is the third paragraph. This is the third paragraph. This is the third paragraph. This is the third paragraph.
👎:
这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。
这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。
This is the third paragraph. This is the third paragraph. This is the third paragraph. This is the third paragraph.
段落和其它块级元素间空一行
👍:
## 一个标题
这是一个段落。这是一个段落。这是一个段落。这是一个段落。
- foo
- bar
这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。
> 一块引用内容
👎:
## 一个标题
这是一个段落。这是一个段落。这是一个段落。这是一个段落。
- foo
- bar
这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。
> 一块引用内容
强调
使用一个、两个和三个 *
分别表示斜体、粗体和粗斜体
👍:
这是一个*斜体*;这是一个**粗体**;这是一个***粗斜体***。
👎:
这是一个_斜体_;这是一个__粗体__;这是一个___粗斜体___;这是一个**混用**。
链接
使用有意义的链接文本
👍:
我的博客是 [Project RC](https://stdrc.cc)。
👎:
我的博客是 Project RC,点击 [这里](https://stdrc.cc) 查看。
使用 <>
快速创建链接
👍:
## 参考资料
- <https://google.github.io/styleguide/docguide/style.html>
👎:
## 参考资料
- [https://google.github.io/styleguide/docguide/style.html](https://google.github.io/styleguide/docguide/style.html)
链接两边加空格,标点符号除外(个人习惯)
👍:
## 标题里的 [某某链接](https://stdrc.cc)
这是一个段落。这是一个段落。中间有个 [某某链接](https://stdrc.cc)。这是一个段落。这是一个段落。
👎:
## 标题里的[某某链接](https://stdrc.cc)
这是一个段落。这是一个段落。中间有个[某某链接](https://stdrc.cc)。这是一个段落。这是一个段落。
图片
不应在文字段落中插入大图
👍:
这是一个段落。这是一个段落。一个超大的图片如下:
![超大的图片](http://example.com/abc.jpg)
这是另一个段落。这是另一个段落。
👎:
这是一个段落。这是一个段落。中间有个 ![超大的图片](http://example.com/abc.jpg)。这是一个段落。这是一个段落。
可使用 HTML 实现图片居中
<p align="center">
<img width="600" height="200" src="http://example.com/abc.jpg">
</p>
行内代码
行内代码两边加空格,标点符号除外
👍:
## 标题里的 `inline` 代码
这是一个段落。这是一个段落。中间有个 `inline code`。这是一个段落。这是一个段落。
👎:
## 标题里的`inline`代码
这是一个段落。这是一个段落。中间有个`inline code`。这是一个段落。这是一个段落。
为文件名、命令、程序代码等应以等宽字体显示的内容使用行内代码样式
👍:
编辑文件 `main.c`,然后运行命令 `gcc main.c`。
👎:
编辑文件 main.c,然后运行命令 gcc main.c。
链接文本中的代码也应使用行内代码样式
👍:
更多文档请参考 [`mmap`](https://man7.org/linux/man-pages/man2/mmap.2.html)。
👎:
更多文档请参考 [mmap](https://man7.org/linux/man-pages/man2/mmap.2.html)。
使用两个 `
转义 `
本身
使用两个 `` ` `` 转义 `` ` `` 本身,例如 ``Foo`Bar``。如果代码中只有 `` ` `` 这一个字符,需在两侧加空格。
代码块
使用 ```
表示代码块
👍:
下面是一个代码块:
```python
def foo():
pass
```
这是另一个段落。
👎:
下面是一个代码块:
def foo():
pass
这是另一个段落。
尽量为代码块标注编程语言
👍:
```python
def foo():
pass
```
👎:
```
def foo():
pass
```
同一个编程语言的代码块应在全文保持语言名称一致
👍:
第一段代码:
```python
def foo():
pass
```
第二段代码:
```python
def foo():
pass
```
👎:
第一段代码:
```python
def foo():
pass
```
第二段代码:
```py
def foo():
pass
```
使用更多 `
转义多个 `
本身
````md
下面是一个代码块:
```python
def foo():
pass
```
这是另一个段落。
````
引用块
引用块中有内容的段落开头 >
右边应加空格,空行不用
👍:
> 第一个段落。第一个段落。第一个段落。第一个段落。
>
> 第二个段落。第二个段落。第二个段落。第二个段落。
👎:
>第一个段落。第一个段落。第一个段落。第一个段落。
>
>第二个段落。第二个段落。第二个段落。第二个段落。
👎:
> 第一个段落。第一个段落。第一个段落。第一个段落。
> <- 这里有个空格
> 第二个段落。第二个段落。第二个段落。第二个段落。
嵌套引用块应在两层的 >
间加空格
👍:
> 第一个段落。第一个段落。第一个段落。下面是个嵌套引用:
>
> > 嵌套引用段落。嵌套引用段落。嵌套引用段落。嵌套引用段落。
> >
> > 嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。
👎:
> 第一个段落。第一个段落。第一个段落。下面是个嵌套引用:
>
>> 嵌套引用段落。嵌套引用段落。嵌套引用段落。嵌套引用段落。
>>
>> 嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。
无序列表
使用 *
或 -
表示无序列表,并在全文保持统一
👍:
- foo
- bar
- bar1
- bar2
- baz
👎:
- foo
- bar
* bar1
* bar2
- baz
另一个列表:
* aaa
* bbb
多级列表使用四个空格缩进
👍:
- foo
- bar
- bar1
- bar2
- baz
👎:
- foo
- bar
- bar1
- bar2
- baz
列表项有多行内容时应缩进到与第一行相同的位置
👍:
- foo
- 这是一个较复杂的列表项,有代码:
```python
def foo():
pass
```
和另一段内容。
- baz
👎:
- foo
- 这是一个较复杂的列表项,有代码:
```python
def foo():
pass
```
和另一段内容。
- baz
有序列表
列表项较多且变更频繁时可全部标为 1.
,由渲染引擎自动编号
1. foo
1. bar
1. bar1
1. bar2
1. baz
列表项较少或变更不频繁时应尽量按正确顺序标号
1. foo
2. bar
3. baz
表格
只针对 GitHub Flavored Markdown(GFM)。
行的两侧不加 |
,标题行下面只使用三个 -
👍:
姓名 | 学号 | 兴趣爱好
--- | --- | ---
张三 | 101 | 打篮球
李四 | 102 | 唱歌
👎:
| 姓名 | 学号 | 兴趣爱好 |
| --- | --- | ------- |
| 张三 | 101 | 打篮球 |
| 李四 | 102 | 唱歌 |
表格内容两侧加空格
👍:
姓名 | 学号 | 兴趣爱好
--- | --- | ---
张三 | 101 | 打篮球
李四 | 102 | 唱歌
👎:
姓名|学号|兴趣爱好
---|---|---
张三|101|打篮球
李四|102|唱歌
删除线
使用 <del>
或 ~~
(如果渲染引擎支持)表示删除线样式
<del>哈哈哈哈!</del>被删除了!