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>被删除了!

其它

称之为“Markdown”或“markdown”,而不是“MarkDown”

使用 .md 作为文件扩展名,而不是 .markdown.mdown

编写内容时遵循 中文写作风格指南

参考资料

评论