makedown教程

Markdown 规范

Markdown 语法在细节的书写方式很多，为了让不同成员的文档产出结构一致，提炼出此规范。
同时为了方便管理和生成文档，该规范同时遵循以下语法，旨在统一书写格式和代码风格，将多种写法统一。

• Markdown 官方语法
• GitHub Markdown 语法
• GitBook Markdown 语法
• Google Style Markdown

此外，对一些排版方面的问题进行了统一。

内容

1. 全局规范
2. 段落
3. 换行
4. 标题
5. 强调
6. 列表
   1. 无序列表
   2. 有序列表
   3. 嵌套列表
7. 链接
   1. 链接的表示
   2. 相对链接和路径
8. 图片
9. 代码块和语法高亮
   1. 行内代码
   2. 多行代码
   3. 缩进式多行代码
   4. 代码块中的内容
10. 数学公式
11. UML
12. 表格
13. 引用文本
14. 任务列表
15. 转义字符
16. 排版规范
    1. 空格
    2. 标点符号
    3. 全角和半角
    4. 名词
17. 推荐工具
18. 延伸阅读

全局规范

• Markdown 文件均使用.md作为后缀 (小写字母)。

段落

• 通过在文本行之间留一个空白行，创建新段落。

换行

• 普通文本换行，使用行末尾两个空格触发，不会形成段落。

标题

• 标题与紧接的上下正文用一个空行隔开。
• #号和文字之间用一个空格隔开。
• 标题层级如下，最多六级。

# H1
## H2
### H3
#### H4
##### H5
###### H6

• 不要使用 = 和 - 来区分标题层级，如：

Alt-H1
========

Alt-H2
--------

强调

• 强调，斜体，用*星号*或_下划线_。

• 重点强调，加粗，用**双星号**或__双下划线__。

• 组合_强调_, 使用**星号和_下划线_**。

• 删除线，使用使用两个波浪线。~~划掉这个~~。

列表

无序列表

通过在一行或多行文本前面添加 - 或 * 可创建无序列表。

- George Washington
- John Adams
- Thomas Jefferson

有序列表

要对列表排序，请在每行前面添加一个编号。

1. James Madison
2. James Monroe
3. John Quincy Adams

嵌套列表

通过在一个列表项下面缩进一个或多个其他列表项，可创建嵌套列表。

缩进采用四个空格。

1.  2 spaces after a numbered list.
    4 space indent for wrapped text.
2.  2 spaces again.

*   3 spaces after a bullet.
    4 space indent for wrapped text.
    1.  2 spaces after a numbered list.
        8 space indent for the wrapped text of a nested list.
    2.  Looks nice, don't it?
*   3 spaces after a bullet.

错误示范：

* One space,
with no indent for wrapped text.
     1. Irregular nesting... DO NOT DO THIS.

即使没有嵌套列表，但是有多行文本时，使用四个空格进行缩进也会时排版更清爽。

*   Foo,
    wrapped.

1.  2 spaces
    and 4 space indenting.
2.  2 spaces again.

如果只是简单的列表项，且没有嵌套列表，列表符号和文本之间可以只用一个空格。

* Foo
* Bar
* Baz.

1. Foo.
2. Bar.

链接

链接的表示

有两种创建链接的方式。

-  [内嵌式链接](https://www.google.com)

    [带标题的内嵌式链接](https://www.google.com "谷歌的主页")

-  [引用式链接][arbitrary case-insensitive reference text]

    [相对引用一个库文件](../blob/master/LICENSE)

    [你可以在引用式链接定义中使用数字][1]

    或者空着什么都不写 [link text itself]

    用来说明引用链接的文字可以放在后面。

    [arbitrary case-insensitive reference text]: https://www.mozilla.org
    [1]: http://slashdot.org
    [link text itself]: http://www.reddit.com

相对链接和路径

可以在文件中定义相对链接和图像或文件路径，以帮助导航到其他文件。

相对链接是相对于当前文件的链接。 例如，如果在仓库根目录下有一个自述文件，而在 docs/CONTRIBUTING.md 中有另一个文件，则自述文件中的 CONTRIBUTING.md 的相关链接如下所示：

[此项目的参与指南](docs/CONTRIBUTING.md)

相对链接更便于克隆仓库。 绝对链接可能无法用于仓库的克隆 - 建议使用相对链接引用仓库中的其他文件。

图片

这是我们的 logo （停留查看标题）

内嵌式
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

引用式
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

代码块和语法高亮

插入程序代码的方式：使用反引号 `（~ 键）。

• 插入行内代码，即插入一个单词或者一句代码的情况，使用 `code` 这样的形式插入。
• 插入多行代码，分别使用一对三反引号 ``` 多行代码 ```。

行内代码

在一般的段落文字中，可以使用反引号 ` 来标记或插入代码区段。

C语言里的函数 `scanf()` 怎么使用？

显示为：

C语言里的函数 scanf() 怎么使用？

多行代码

• 在需要高亮的代码块的前一行及后一行使用三个反引号 ```（~ 键）
• 同时第一行反引号后面，输入代码块所使用的语言，实现代码高亮。
  比如高亮 python 代码块：

```python
#!/usr/bin/env python3
print("Hello, World!");
```

显示为：

#!/usr/bin/env python3
print("Hello, World!");

缩进式多行代码

注意：

• 缩进式插入前方必须有空行；
• 缩进 4 个空格或是 1 个制表符；
• 一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

代码：

此处有空行
    #include  <stdio.h>
    int main(void)
    {
        printf("Hello world\n");
    }

显示为：

    #include  <stdio.h>
    int main(void)
    {
        printf("Hello world\n");
    }

代码块中的内容

代码区块中，一般的 Markdown 语法不会被转换，像是 * 便只是星号，这表示你可以很容易地以 Markdown 语法撰写 Markdown 语法相关的文件。

Markdown 语法展示

数学公式

GitLab 原生支持 KaTex 表示的数学公式。

• 行内公式：使用 $`a<sup>2+b</sup>2=c^2`$ 这样的形式插入，显示为 $‘a^2+b^2=c^2‘$ 。

• 行间公式 & 代码块

代码：

```math
E(\mathbf{v}, \mathbf{h}) = -\sum_{i,j}w_{ij}v_i h_j - \sum_i b_i v_i - \sum_j c_j h_j
```

显示为：

E(\mathbf{v}, \mathbf{h}) = -\sum_{i,j}w_{ij}v_i h_j - \sum_i b_i v_i - \sum_j c_j h_j

UML

代码：

```mermaid
sequenceDiagram
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

显示为：

表格

表格不是 Markdown 规范的核心部分，但是它是 GFM 的一部分，表格的使用请参考 GFM。

冒号可以用来对齐列。

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

外部的管道符 (|) 是可选的，而且不需要优雅的排列 Markdown 。你还可以在表格中内嵌其他 Markdown 。

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

显示为：

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

Markdown	Less	Pretty
Still	renders	nicely
1	2	3

说明：Google Style 不建议编写太复杂的列表，复杂的表格在 Markdown 中可读性差且不方便维护。

引用文本

可以使用 > 来引用文本。

用 Abraham Lincoln 的话来说：

> Pardon my french

显示为：

用 Abraham Lincoln 的话来说：

Pardon my french

任务列表

要创建任务列表，在列表项目前面加一个常规空格字符，后接 [ ] 。 要将任务标记为已完成，请使用 [x] 。

- [x] 完成更改
- [ ] 推送提交到 GitHub
- [ ] 打开拉取请求

显示为：

• 完成更改
• 推送提交到 GitHub
• 打开拉取请求

转义字符

反斜线 \ 用于插入在 Markdown 语法中有特殊作用的字符。

这是用来 *演示* 的 _文本_

这是用来 \*演示\*的 \_文本\_

这是用来 `演示` 的 `code`

这是用来 \`演示\` 的 \`code\`

这是用来 演示 的 文本

这是用来 *演示* 的 _文本_

这是用来 演示 的 code

这是用来 `演示` 的 `code`

这些字符包括：

\
`
*
_
{}
[]
()
#
+
-
.
!

排版规范

空格

• 中英文之间用空格隔开。

  正确：

  在 LeanCloud 上，数据存储是围绕 AVObject 进行的。

  错误：

  在LeanCloud上，数据存储是围绕AVObject进行的。

  在 LeanCloud上，数据存储是围绕AVObject 进行的。

  完整的正确用法：

  在 LeanCloud 上，数据存储是围绕 AVObject 进行的。每个 AVObject 都包含了与JSON 兼容的 key-value 对应的数据。
  数据是 schema-free 的，你不需要在每个 AVObject 上提前指定存在哪些键，只要直接设定对应的 key-value 即可。

  例外：对一些特定名词，如「豆瓣FM」等产品名词，按照官方所定义的格式书写。

• 中文与数字之间需要使用空格。

  正确：

  今天出去买菜花了 5000 元。

  错误：

  今天出去买菜花了 5000元。

  今天出去买菜花了5000元。

• 数字与单位之间无需增加空格。

  正确：

  我家的光纤入户宽带有 10Gbps，SSD 一共有 10TB。

  错误：

  我家的光纤入户宽带有 10 Gbps，SSD 一共有 20 TB。

• 度、百分比与数字之间不需要添加空格：

  正确：

  今天是 233° 的高温。

  新 MacBook Pro 有 15% 的 CPU 性能提升。

  错误：

  今天是 233 ° 的高温。

  新 MacBook Pro 有 15 % 的 CPU 性能提升。

• 全角标点与其他字符之间不加空格。

  正确：

  刚刚买了一部 iPhone，好开心！

  错误：

  刚刚买了一部 iPhone ，好开心！

标点符号

• 不重复使用标点符号。

  正确：

  德国队竟然战胜了巴西队！

  她竟然对你说「喵」？！

  错误：

  德国队竟然战胜了巴西队！！

  德国队竟然战胜了巴西队！！！！！！！！

  她竟然对你说「喵」？？！！

  她竟然对你说「喵」？！？！？？！！

全角和半角

什么是全角（全形）与半角（半形）符号？请查看维基百科词条全角和半角。

• 使用全角中文标点。

  正确：

  嗨！你知道嘛？今天前台的小妹跟我说「喵」了哎！

  核磁共振成像（NMRI）是什么原理都不知道？JFGI！

  错误：

  嗨! 你知道嘛? 今天前台的小妹跟我说 “喵” 了哎!

  嗨!你知道嘛?今天前台的小妹跟我说"喵"了哎!

  核磁共振成像 (NMRI) 是什么原理都不知道? JFGI!

  核磁共振成像(NMRI)是什么原理都不知道?JFGI!

• 数字使用半角字符。

  正确：

  这件蛋糕只卖 1000 元。

  错误：

  这件蛋糕只卖 １０００ 元。

• 遇到完整的英文整句、特殊名词，其內容中使用半角标点。

  正确：

  乔布斯那句话是怎么说的？「Stay hungry, stay foolish.」

  推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。

  错误：

  乔布斯那句话是怎么说的？「Stay hungry，stay foolish。」

  推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。

名词

• 专有名词使用正确的大小写。

  大小写相关用法原属于英文书写范畴，不属于本文讨论內容，在这里只对部分易错用法进行简述。

  正确：

  使用 GitHub 登录

  我们的客户有 GitHub、Foursquare、Microsoft Corporation、Google、Facebook, Inc.。

  TensorFlow, PyTorch

  错误：

  使用 github 登录

  使用 GITHUB 登录

  使用 Github 登录

  我们的客户有 github、foursquare、microsoft corporation、google、facebook, inc.。

  我们的客户有 GITHUB、FOURSQUARE、MICROSOFT CORPORATION、GOOGLE、FACEBOOK, INC.。

  我们的客户有 Github、FourSquare、MicroSoft Corporation、Google、FaceBook, Inc.。

  Tensorflow, Pytorch

• 不要使用不地道的缩写。

  正确：

  我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。

  错误：

  我们需要一位熟悉 Js、h5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。

推荐工具

• Typora
• 在线 Markdown 编辑器

延伸阅读

• Markdown 语法
• Google Markdown 风格
• GitHub Flavored Markdown 规格
• GitHub 上的撰写和规范
• 熟悉 Markdown
• Gitbook 的 Markdown
• Markdown 中文排版指北