Markdown 书写风格指南

在线 Markdown 书写风格指南

关于

参考 原始设计规范, CommonMark 和其他扩展。

本项目由社区驱动, 尝试达成共识。 只有当社区达成一致时,项目维护者才将其加入此文档。

讨论将在 GitHub issue 展开。

本文档源代码托管在 GitHub

设计目标

著名用户

你在使用这份风格指南吗? 将你的名字添加到我们的 wiki.

如果你很著名? 给我们发送一个 pull request.

如果你是一个著名的用户:

如果你的项目满足以下条件,请毫不犹豫的发送 pull request吧:

可选

有争议的内容会给出多种可选择的风格。

每一种可选项会用小写连字符分割提示。

每一种可选项都会有以下格式的说明:

# Option key:value

The first option header that appears in this text is the default value.

比如, 如果自动换行 wrap 有三种风格,我们会给出关键词 wrap, 并且给每一种风格一种名字,比如:

# Option wrap:space
# Option wrap:no
# Option wrap:sentence

当引用此标准时,准确标明所有非默认选项的风格,并用逗号分割:

Use the Markdown Style Guide wrap:space, code:indented

书写约定

当这份风格指南需要多种表示空格的方式,或者在代码区块开始或结束时出现空格时,点号将被用来表示空格。

例如:

a, 空格, b:

a b

a, 2 空格, b:

a..b

空格, ab:

.ab

ab, 空格:

ab.

可供选择

Google 风格指南

这份指南最初从carwin/markdown-styleguide fork 得来. 原始文档已经被大规模的改动,一些决定已经被修改,几乎已经找不到原文。

Miguel de Icaza (GNOME, Mono) 已经提出一份简短的风格指南 http://tirania.org/blog/archive/2014/Sep-30.html

Lint tools

在 Stack Exchange 上的提问: http://softwarerecs.stackexchange.com/questions/7138/markdown-lint-tool/

通用规则

文件

文件扩展名

使用 .md.

解释: 为什么不使用 .mkd 或者 .markdown?

文件名

文件名建议使用如下的风格:

建议使用:

file-name.md

不建议, 多个连续的连字符:

file--name.md

不建议, 包围的连字符:

-file-name-.md

解释: 为何不使用下划线和驼峰大小写?连字符是现在最流行的网址分隔符,并且 Markdown 文件在上下文中经常使用:

空白

新行

不要 使用连续两空行,也就是说,不要连续使用两个换行符,除非是在代码块中不得已而必须出现。

以回车换行结束文件。不要在文件结束时留下空行。

不要 在行尾留空格除非是在行尾空出两个空格插入换行符。

建议使用:

- list
- list

# Header

建议, 代码区块:

The markup language X requires you to use triple newlines to separate paragraphs:

    p1


    p2

不建议:

- list
- list


# Header

解释: 多空行占用更多的竖直屏幕空间,并且会严重影响到可读性。

句子结束空格

可选 space-sentence:1

句子结束使用一个空格

不建议, 使用2个空格:

First sentence.  Second sentence.

建议使用:

First sentence. Second sentence.

解释: 相比于space-sentence:2的优点:

相较于 space-sentence:2 的优势:

可选 space-sentence:2

不建议, 单个空格:

First sentence. Second sentence.

建议使用:

First sentence.  Second sentence.

自动换行

可选 wrap:inner-sentence

尝试将一行限制在 80 个字符以下,将长段落按照以下的逻辑分开,例如:

一行中超过80个字符是可以接受的,但是记住长句子不适合阅读,并且在 git diff 中会很难看。

设置你的文本编辑器对 Markdown 文件一行不要超过80字符,以免忘记。

建议使用:

This is a very very very very very very very very very very very very very long not wrapped sentence.
Second sentence of of the paragraph,
third sentence of a paragraph
and the fourth one.

解释:

缺点:

可选 wrap:no

不要自动换行.

解释: 很容易编辑。但是长句子的 diffs 很难阅读。

可选 wrap:space

在超过80个字符的第一个单词换行。

解释: 源文件易读,并且文本编辑器支持。Diff 比较难读,并且修改困难。

可选 wrap:sentence

解释: 和 wrap:inner-sentence 相似的优点, 但是规则通俗易懂: 在句号后换行。对于长句子依然面临 Diff 难以阅读的困扰。

著名事件: ProGit 2.

代码

Shell中美元符号

不要 在 shell 代码前加 $ 符号,除非你想要展示命令的输出。

如果目的是表明确切的语言,那么直接在代码前标明。

解释: 复制粘贴比较困难,不利于阅读。

建议使用:

echo a
echo a > file

不建议:

$ echo a
$ echo a > file

建议, 展示输出:

$ echo a
a
$ echo a > file

建议, 在代码前标明代码语言:

Use the following Bash code:

echo a
echo a > file

标记代码内容

使用代码块,或者行内代码:

不要标记为代码:

拼写和语法

使用正确的拼写和语法。

尽量选用英语,更准确的说美式英语。 解释: 美式英语使用者占有最大的GDP,尤其是在计算机行业。

类似 URL 或者代码,添加代码标记,这样拼写检查程序会自动忽略。

注意大小写敏感的拼写错误,尤其是项目名,品牌名,或者缩写。

一旦有疑惑,尽量选用和维基百科相同的缩写。

避免使用非正式的缩写:

区块

换行符

避免使用换行符, 因为他们没有被广泛认可的语义。

在少数确实需要使用的时候,在行尾使用两个空格。

标题

可选 header:atx

不建议:

Header 1
========

Header 2
--------

### Header 3

建议使用:

# Header 1

## Header 2

### Header 3

可选 header:setex

不建议:

# Header 1

## Header 2

### Header 3

建议使用:

Header 1
========

Header 2
--------

### Header 3

顶级标题

如果你想要 HTML 直接输出,这样唯一的 h1 标记就是输出的第一件事,并且会成为文档的标题。这就是HTML的顶级标题。

h1 标题的产生受到使用的 Markdown 引擎的直接影响: 一些引擎会从元数据(metadata)中产生标题,比如 Jekyll 就是从 front-matter 中产生标题。

将顶级标题保存为元数据(metadata)可以更加方便的在其他地方使用, 比如,在全局索引中,但也有缺点,比如降低了可读性和移植性。

如果目的不是生成顶级标题, include it in your markdown file. E.g., GitHub.

索引文件中的顶级标题比如 README.md 或者 index.md 应该作为他们父目录的标题。

顶级标题的缺点:

顶级标题的优点:

标题大小写

标题结尾

显示标题的内容,而不是用新标题和水平线紧随其后:

# Header

Content

---

Outside header.

标题长度

保证标题越短越好。

避免使用长句子,总结长句子作为标题,然后将长句子作为标题下的第一小节。

解释: 以后引用方便,尤其是自动生成 IDs 或者生成 TOC 。

建议使用:

# Huge header

Huge header that talks about a complex subject.

不建议:

# Huge header that talks about a complex subject

标题结尾标点

不要 在标题中以 : 结尾。

解释: 每一个标题都是接下来内容的简介,这也就正是冒号的作用。

不要 在标题中以 . 结尾。

解释: 每一个标题都包含一个简短的句子,也就不需要句号来分隔他们。

建议使用:

# How to do make omelet

不建议:

# How to do make omelet:

不建议:

# How to do make omelet.

标题同义词

标题用作用户索引的关键词。

正由于这个原因,你可能希望在标题中用多个关键词。

要做到这一点,简单的创建一个同义词标题在主标题之前,并且标题下不包含内容。

比如:

# Purchase

# Buy

You give money and get something in return.

每一个同层级的空标题都假定是同义的。如果层级不一样,那就是另外的含义:

# Animals

## Dog

引用

列表

标记

无序

使用连字符.

建议使用:

- a
- b

不建议:

* a
* b
+ a
+ b

解释:

有序

尽量选用 1. 来标记有序的列表, 除非你打算通过数字在相同 Markdown 文件或者外部文件中引用他们。

尽量使用无序的列表,除非有通过数字引用的需求。

最佳则是从来不通过序号来引用他们:

- a
- c
- b

较好的方法, 仅仅使用 1.:

1. a
1. c
1. b

较差的方法, 不要通过序号来标注列表项的顺序:

1. a
2. c
3. b

可接受的, 使用文本引用:

The ouput of the `ls` command is of the form:

    drwx------  2 ciro ciro        4096 Jul  5  2013 dir0
    drwx------  4 ciro ciro        4096 Apr 27 08:00 dir1
    1           2

Where:

1. permissions
2. number of files directory contains

可接受,通过外部 markdown 文件引用:

Terms of use.

1. I will not do anything illegal.
2. I will not do anything that can harm the website.

解释:

列表项中的空格

可选 list-space:mixed

不建议, 每一项一行:

-   a
-   b

建议使用:

- a
- b

不建议, 每一项一行:

1.  a
1.  b

建议使用:

1. a
1. b

每一项超过一行,不建议:

- item that
  is wrapped

- item 2

建议使用:

-   item that
    is wrapped

-   item 2

每一项超过一行,不建议:

- a

  par

- b

建议使用:

-   a

    par

-   b
可选 list-space:1

列表项标记前总是留有一个空格。

不建议, 使用三个空格:

-   a

    b

-   c

建议使用:

- a

  b

- c

不建议, 两个空格:

1.  a

    b

1.  c

建议使用:

1. a

   b

1. c
解释: list-space mixed vs 1

使用 list-space:1 的有点:

使用 list-space:1 的缺点:

列表内容的缩进

列表中内容的缩进层级必须和第一个列表项一致:

不建议:

-   item that
  is wrapped

-   item 2

建议使用:

-   item that
    is wrapped

-   item 2

不建议:

-   item 1

  Content 1

-   item 2

      Content 2

建议(如果符合列表标记之后的空格):

-   item 1

    Content 1

-   item 2

    Content 2

不建议:

- item 1

    Content 1

- item 2

    Content 2

建议(如果符合列表标记之后的空格):

- item 1

  Content 1

- item 2

  Content 2

避免开始直接使用缩进的代码列表项,因为这样不容易实现。CommonMark states that 一个单独的空格需要加入:

-     code

  a

列表中的空行

如果每一个列表项只有一行, 不要在列表项之间增加空行,否则,在每一个列表项之间增加空行。

不建议, single lines:

- item 1

- item 2

- item 3

建议使用:

- item 1
- item 2
- item 3

多行情况下,不建议:

-   item that
    is wrapped
-   item 2
-   item 3

建议使用:

-   item that
    is wrapped

-   item 2

-   item 3

不建议, 多行:

-   item 1

    Paragraph.

-   item 2
-   item 3

建议使用:

-   item 1.

    Paragraph.

-   item 2

-   item 3

不建议, 多行:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2
-   item 3

建议使用:

-   item 1

    - item 11
    - item 12
    - item 13

-   item 2

-   item 3

解释: 如果没有空行,很难分别多行的列表项开始和结束。

列表外的空行

列表外建议留有一空行。

不建议:

Before.
- item
- item
After.

建议使用:

Before.

- list
- list

After.

列表项首字母大小写

每一个 list 使用原来在句子中的大小写.

建议使用:

I want to eat:

- apples
- bananas
- grapes

因为它可以被如下替换:

I want to eat apples
I want to eat babanas
I want to eat grapes

建议使用:

To ride a bike you have to:

- get on top of the bike. This step is easy.
- put your foot on the pedal.
- push t the pedal. This is the most fun part.

因为它可以被如下替换:

To ride a bike you have to get on top of the bike. This step is easy.
To ride a bike you have to put your foot on the pedal.
To ride a bike you have to push the pedal. This is the most fun part.

建议使用:

# How to ride a bike

- Get on top of the bike.
- Put your feet on the pedal.
- Make the pedal turn.

因为它可以被如下替换:

# How to ride a bike

Get on top of the bike.
Put your feet on the pedal.
Push the the pedal.

列表项结尾标点

列表项结尾标点,除非:

否则, 如果以句号结尾的话,省略标点.

不建议使用,以:

- apple.
- banana.
- orange.

建议使用:

- apple
- banana
- orange

同上:

- go to the market
- then buy some fruit
- finally eat the fruit

建议使用, 不以句号结尾,而是以其他标点结尾:

- go to the marked
- then buy fruit?
- of course!

不建议, 多个句子时末尾不加标点:

- go to the market
- then buy some fruit. Bad for wallet
- finally eat the fruit. Good for tummy

建议使用:

- go to the market
- then buy some fruit. Bad for wallet.
- finally eat the fruit. Good for tummy.

注意:没有任何理由阻止,一个列表项以句号结尾,另一个列表项没有。

不建议, 多段落:

-   go to the market

-   then buy some fruit

    Bad for wallet

-   finally eat the fruit

    Good for tummy

建议使用:

-   go to the market

-   then buy some fruit.

    Bad for wallet.

-   finally eat the fruit.

    Good for tummy.

不建议, 如果以大写字母开头,添加标点:

- Go to the market
- Then buy some fruit
- Finally eat the fruit

建议使用:

- Go to the market.
- Then buy some fruit.
- Finally eat the fruit.

定义列表

避免 使用定义列表扩展,因为他并没有被多数实现,也没有出现在 CommonMark.

相反, 使用:

代码区域

可选 code:fenced

仅仅使用 fenced code blocks.

和缩进代码区块比较:

不要 缩进 fenced code blocks.

总是指定代码的语言。

建议使用:

```ruby
a = 1
```

不建议:

```
a = 1
```

可选 code:indented

仅仅使用缩进代码区域。

代码区域缩进4个空格。


代码区块必须以一空行隔开。

尽量在代码块之前使用冒号结束短语 :

建议使用:

use this code to blow up your PC:

    sudo rm -rf /

不建议, 没有冒号

use this code to blow up your PC

    sudo rm -rf /

水平横线

不要 使用水平线除非表明End of a header.

解释:

使用 3 个无空格连字符:

---

表格

扩展.

建议表格:

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

解释:

分离相连的列表

分离连续:

使用一个空白的 HTML 注释 <!-- -->.

- list 1
- list 1

<!-- -->

- list 2
- list 2
    code 1
    code 1

<!-- -->

    code 2
    code 2
> blockquote 1
> blockquote 1

<!-- -->

> blockquote 2
> blockquote 2
- list
- list

<!-- -->

    code outside list
    code outside list

Span元素

不要 使用内部空格。

建议使用:

**bold**
`code`
[link](http://a.com)
[text][name]

不建议:

** bold **
` code `
[ link ]( http://a.com )
[text] [name]

对于空格至关重要的行内代码:

建议使用:

使用连字符并跟随一个空格来表示无序列表。

解释: 大多数的浏览器不会生成包围的空格,或者复制的时候不会将他们添加到粘贴板。

链接:

定义:

建议使用:

[id2]     http://long-url.com
[long id] http://a.com        "name 1"

不建议, 没有安装 id 排序:

[b] http://a.com
[a] http://b.com

不建议, 没有对齐:

[id] http://id.com
[long id] http://long-id.com

单引号或双引号标题

使用双引号,不要 使用单引号。

解释: 单引号并不是在所有的实现中都有效,但是双引号可以。

强调

加粗

使用双星号格式: **bold**.

解释: 比双下划线格式__bold__更加常见和可读性更高.

斜体

使用单星号格式: *italic*.

解释:

大写强调

不要 使用大写来强调: 使用强调语法例如 加粗 或者 斜体

解释: CSS 有 text-transform:uppercase 属性,如果你愿意的话,可以轻松在全网站实现相同的效果。

强调与标题

不要 使用强调元素(加粗或者斜体) 来介绍多行区块: 使用标题代替.

解释: 这个就是确切的标题的语义, 使用强调的并不是必须的。作为结果,许多实现,给标题增加有用的功能,并没有给强调元素,比如自动 id 来更加容易的引用标题。

建议使用:

# How to make omelets

Break an egg.

...

# How to bake bread

Open the flour sack.

...

不建议:

**How to make omelets:**

Break an egg.

...

**How to bake bread:**

Open the flour sack.

...

所有自动链接必须以字串 http 开始。

特别的, 不要 在相对链接时使用自动链接。如果遇到相对链接,使用括号的方式创建链接。

建议使用:

[file.html](file.html)

不建议:

<file.html>

建议使用:

<https://github.com>

不建议:

<github.com>

解释: 将自动链接从HTML tags区分开很困难. 如果你想要一个相对的链接指向一个 script 的文件?

不要 使用电子邮件自动链接 <address@example.com>. 使用纯HTML .

解释: 标准 markdown 设计规范这样描述:

“performs a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots”.

因此, 输出是随机的,丑陋的, 并且像规范中提到的:

but an address published in this way will probably eventually start receiving spam