原文地址: Markdown style guide

译者: ck

Markdown 格式手册

Markdown 很优秀的一大原因是它可以通过编写纯文本文件而得到良好的格式化输出. 为了方便下一位文档使用者, 尽可能保证整个Mardown 文档语法简单而且一致.

我们要寻求以下三个目标的平衡:

原文件的可读性和便携性.
Markdown 文件随着时间的推移和团队的使用是可维护的.
语法简单并且易于记忆

文档布局

一般情况下, 大部分文档能从类似下面的布局方式获益:

# 文档标题

简短介绍

[TOC]

## 主题

主题内容

## 参见

* https://link-to-more-info

# 文档标题: 第一个标题最好是一级标题, 而且最好和文件名相同或相似. 第一个标题通常作用于整个文件
作者: 可选项. 如果你需要声明文章所有权或者自豪于写出这个文档, 可以在标题下加上自己的名字. 一般文档的修改历史足够确认文档的作者.
简短介绍: 要用1-3句话对标题提供很好的介绍. 假设自己是一个新手, 需要阅读或者扩展"Foo"文档, 新手需要知道你原来认为理所当然的概念. 新手需要知道: "Foo 是什么? 为什么我要扩展它"
[TOC]: 如果你使用了支持目录的应用, 例如: Gitiles. 将 [TOC] 放到简短说明后面. 详见[TOC]
## 主题: 剩下的标题级别从二级开始.
## 参见: 把相关连接放到文档的底部, 方便找到更详细的内容或者找到当前页面没有但用户需要了解的内容.

字符行限制

尽可能遵从项目中关于字符行的限制. 长的URLs和表格总是会破坏这些限制. (标题也不能被包装, 但我们鼓励尽可能让标题短一点). 或者, 可以对长文本进行包装:

Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
hendrerit, id nobis saperet fuisset ius.

*   Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
    interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).

通常在长链接前后加入换行符以增加可读性, 也可以遵守字符长度的限制.

行尾空格

不要使用行尾空格, 可以使用行尾反斜线换行.

CommonMark spec 规定行尾的两个空白在html中等价于<br/>标签. 但是许多目录树都有对尾部空白的预提交检查, 并且许多IDEs都会清除掉尾部空格.

最佳实践是完全避免<br/>标签的使用. Markdown 使用空白行为作为简单的段落标签: 请继续使用空白行.

标题

ATX-style headings

## Heading 2

标题行下添加=或者-可以指定该行是标题, 但这不符合剩下的标题语法. 用户可能会问: --- 表示一级标题还是二级标题?

Heading - do you remember what level? DO NOT DO THIS
----------

在标题周围加上空行

最好在#和新行的前面和后面加上空白行

...text befor.

# Heading 1

Text after...

缺少空行会使原文本可读性差点.

...text before

# Heading 1
Text after... DO NOT DO THIS.

列表

对于长列表使用偷懒的有序列表

Markdown 聪明到可以在HTML结果中正确渲染有序列表. 对于可能发生改变的长列表, 尤其是嵌套的长列表, 最好使用懒有序列表.

1. Foo.
1. Bar.
    1. Foofoo.
    1. Barbar.
1. Baz.

如果列表很小而且不太可能改变它, 最好使用完整有序列表. 这样可以增加原文本的可读性.

1. Foo.
2. Bar.
3. Baz.

嵌套列表的间隔

在嵌套列表中, 使用4个间隔缩进有序和无序列表:

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 ident for wrapped text.
	1. Iffegular nesting... DO NOT DO THIS.

没有嵌套时, 使用4个间隔缩进也有助于原文本和渲染后的文本保持一致.

*   Foo,
    wrapped.

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

当列表很小, 没有嵌套, 只有简单的一行. 一个间隔足够满足所有形式的列表

* Foo
* Bar
* Baz

1. Foo.
2. Bar.

代码

反引号 标记了inline code, 将会渲染所有包围的内容. 主要用于短代码和字段名称:

You'll want to run `really_cool_script.sh arg`.

Pay attention to the `foo_bar_whammy` field in that table.

使用反引号标记抽象意义的文件名, 而不是具体的文件:

Be sure to update your `README.md`!

反引号通常是转义Markdown元字符的好方法. 代码字体可以合理的展示转义字符.

代码块

对于超过一行的代码, 使用代码块:

```python
def Foo(self, bar):
  self.bar = bar
```

声明语言

最好声明语言类型, 那样可以语法高亮, 也方便编辑器对语言猜测.

四个间隔的缩进也能被解释为一个代码块, 这种方式看起来清晰并且易读性很好, 只是不能指定语言类型. 鼓励在有很多代码片段是使用:

You'll need to run:

    bazel run :thing -- --foo

And then:

    bazel run :another_thing -- --bar

And again:

    bazel run :yet_again -- --baz

转义换行符

因为大部分命令行片段需要被复制粘贴到terminal 中, 所以最好转义以下换行符. 在行的末尾加一个反斜线即可:

```shell
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
```

列表中嵌套程序块

如果在列表中需要一个程序块, 请缩进程序块以确保列表不被打断.

*   Bullet.

    ```c++
    int foo;
    ```

*   Next bullet.

也可以使用4 个间隔创建代码块. 只需要在列表缩进后添加4个间隔即可:

*   Bullet.

        int foo;

*   Next bullet.

链接

长链接使Markdown 原文件可读性变差, 也破坏了每行80个字符的限定. 请尽可能缩短链接长度.

使用有丰富信息的Markdown 链接标题

Markdown 的链接语法可以设置一个链接标题, 就像HTML一样, 请高效使用.

读者快速浏览文档时, "link" 或者"here" 这种没有信息含量的标题是对空间的一种浪费.

See the syntax guide for more info: [link](syntax_guide.md).
Or, check out the style guide [here](style_guide.md).
DO NOT DO THIS.

请自然的写出句子, 然后在句子中用链接包围最合适的短语.

图片

尽量少用图片, 最好是一些简单的截图. 该手册的设计目标是让用户使用纯文本快速的沟通业务, 减少读着的分心和作者的拖延.

参见 image syntxt

优先选择列表而非表格

最好在Markdown 中只使用小的表格. 大的, 复杂的表格在源码状态很难阅读, 而且后期维护会非常痛苦.

Fruit | Attribute | Notes
--- | --- | --- | ---
Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.

DO NOT DO THIS

紧凑一点的列表和子标题就可以显示相同的信息, 这也更容易编辑.(ck注: 图片信息尽可能也用这种方式展示)

## Fruits

### Apple

* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet

Apples keep doctors away.

### Banana

* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet

Contrary to popular belief, most apes prefer mangoes.

有时候也会需要一个小的表格

Transport | Favored by | Advantages
--- | --- | ---
Swallow | Coconuts | Otherwise unladen
Bicycle | Miss Gulch | Weatherproof
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out

强烈建议用Markdown 标签而不是HTML标签

请尽可能的使用Markdown语法, 避免HTML元素的入侵. 如果Markdown 不能做成你想要的, 请重新考虑你是否需要它. 除了大的表格, Markdown 几乎能完成所有需求.

任何一点HTML 或JavaScript 的入侵都会减少文档的可读性和可移植性. 这会限制和其它工具的整合, 其它工具可能会将源文件显示为纯文本或者渲染它.

参见Philosophy.

Gitiles 不会渲染 HTML.

[译] Google Markdown 格式手册