styleguide

Markdown 风格指南

Markdown 的魅力很大程度上在于能够编写纯文本并获得出色的格式化输出。为了给下一位作者提供干净的模板，您的 Markdown 应该尽可能简单，并与整个语料库保持一致。

我们力求平衡三个目标

1. 源文本是可读且可移植的。
2. Markdown 语料库在一段时间内和跨团队都是可维护的。
3. 语法简单且易于记忆。

目录

1. 最低可行文档
2. 更好胜于最好
3. 大写
4. 文档布局
5. 目录
6. 字符行数限制
7. 尾随空格
8. 标题
   1. ATX 样式的标题
   2. 为标题使用唯一的、完整的名称
   3. 为标题添加间距
   4. 使用单个 H1 标题
   5. 标题和大写
9. 列表
   1. 对于长列表，使用惰性编号
   2. 嵌套列表间距
10. 代码
    1. 内联
    2. 使用代码跨度进行转义
    3. 代码块
       1. 声明语言
       2. 转义换行符
       3. 使用围栏式代码块而不是缩进式代码块
       4. 在列表中嵌套代码块
11. 链接
    1. 在 Markdown 中对链接使用显式路径
    2. 除非在同一目录中，否则避免使用相对路径
    3. 使用信息丰富的 Markdown 链接标题
    4. 参考链接
       1. 对长链接使用参考链接
       2. 使用参考链接以减少重复
       3. 在第一次使用后定义参考链接
12. 图片
13. 表格
14. 强烈建议使用 Markdown 而不是 HTML

最低可行文档

一小套新的、准确的文档胜过分散的、松散的、处于各种失修状态的“文档”集合。

Markdown 方式鼓励工程师掌握其文档的所有权，并以与我们保持测试良好的热情相同的热情来保持文档的最新状态。努力做到这一点。

• 确定你真正需要的东西：发布文档、API 文档、测试指南。
• 经常且少量地删除无用内容。

更好胜于最好

内部文档审查的标准与代码审查的标准不同。 审查人员应要求改进，但一般来说，作者应该始终能够调用“更好/最好规则”。

快速迭代是你的朋友。 为了获得长期改进，作者在进行短期改进时必须保持高效。 为每个 CL 设置较低的标准，以便更多此类 CL 可以发生。

作为文档 CL 的审阅者

1. 如果合理，立即 LGTM 并相信评论将得到适当修复。
2. 最好提出替代方案，而不是留下模糊的评论。
3. 对于重大更改，请开始你自己的后续 CL。 尤其要尽量避免“你还应该……”形式的评论。
4. 在极少数情况下，如果 CL 实际上使文档变得更糟，请阻止提交。 可以要求作者恢复。

作为作者

1. 避免在琐碎的争论中浪费时间。 早点投降并继续前进。
2. 根据需要经常引用更好/最好规则。

大写

使用产品、工具和二进制文件的原始名称，保留大小写。 例如

# Markdown style guide

`Markdown` is a dead-simple platform for internal engineering documentation.

而不是

# markdown bad style guide example

`markdown` is a dead-simple platform for internal engineering documentation.

文档布局

一般来说，文档受益于以下布局的某些变体

# Document Title

Short introduction.

[TOC]

## Topic

Content.

## See also

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

1. # 文档标题：第一个标题应为一级标题，最好与文件名相同或几乎相同。 第一个一级标题用作页面 <title>。

2. author：可选。 如果你想声明对文档的所有权，或者你对文档感到非常自豪，请在标题下添加你自己的信息。 但是，修订历史通常就足够了。

3. 简短介绍。 1-3 句话，提供主题的高级概述。 想象一下你是一个完全的新手，偶然发现了你的“扩展 Foo”文档，并且不知道你认为理所当然的最基本信息。 “什么是 Foo？ 我为什么要扩展它？”

4. [TOC]：如果你使用的托管支持目录，例如 Gitiles，请将 [TOC] 放在简短介绍之后。 见 [TOC] 文档。

5. ## 主题：其余标题应从 2 级开始。

6. ## 另见：在底部放置杂项链接，供想要了解更多信息或找不到他们需要的信息的用户使用。

目录

使用 [TOC] 指令

使用 [TOC] 指令，除非你所有的内容都在笔记本电脑上的首屏¹ 上。

将 [TOC] 指令放在介绍之后

将 [TOC] 指令放在页面的介绍之后和第一个 H2 标题之前。 例如

# My Page

This is my introduction **before** the TOC.

[TOC]

## My first H2

# My Page

[TOC]

This is my introduction **after** the TOC where it should not be.

## My first H2

对于通过视觉方式阅读文档的用户来说，你的 [TOC] 指令的放置位置并不重要，因为 Markdown 始终将 TOC 显示在页面的顶部和右侧。 但是，当涉及屏幕阅读器或键盘控件时，[TOC] 的放置位置非常重要。

那是因为 [TOC] 会将目录的 HTML 插入到 DOM 中，无论你在 Markdown 文件中包含该指令的位置。 例如，如果你将该指令放在文件的最底部，则屏幕阅读器直到到达文档末尾才会读取它。

字符行数限制

Markdown 内容遵循 80 个字符行数限制的剩余约定。 为什么？ 因为这是我们大多数人对代码所做的事情。

• 工具集成：我们所有的工具都是围绕代码设计的，因此我们的文档按照类似规则格式化的越多，这些工具的效果就越好。 例如，代码搜索不会软换行。

• 质量。 工程师在创建和编辑 Markdown 内容时，越能使用他们常用的编码习惯，质量就越好。 Markdown 利用了我们已经拥有的出色审查文化。

例外

80 个字符规则的例外情况包括

• 链接
• 表格
• 标题
• 代码块

这意味着带有链接的行以及任何相关的标点符号都可以超出第 80 列

*   See the
    [foo docs](https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.md).
    and find the logfile.

但是，请注意链接之前和之后的文本会被换行。

表格也可能很长。 但是，有一些 创建简短、可读表格的最佳实践。

Foo                                                                           | Bar | Baz
----------------------------------------------------------------------------- | --- | ---
Somehow-unavoidable-long-cell-filled-with-content-that-simply-refuses-to-wrap | Foo | Bar

尾随空格

不要使用尾随空格。 使用尾随反斜杠来断行。

CommonMark 规范规定，一行的末尾的两个空格应插入一个 <br /> 标签。 但是，许多目录都有针对尾随空格的预提交检查，并且许多 IDE 无论如何都会清理它。

谨慎地使用尾随反斜杠

For some reason I just really want a break here,\
though it's probably not necessary.

最佳实践是避免完全需要 <br />。 一对换行符将创建一个段落标签； 习惯它。

标题

ATX 样式的标题

# Heading 1

## Heading 2

带有 = 或 - 下划线的标题可能难以维护，并且与标题语法的其余部分不符。 编辑器必须问：--- 是指 H1 还是 H2？

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

为标题使用唯一的、完整的名称

为每个标题使用唯一的和完全描述性的名称，即使对于子部分也是如此。 由于链接锚点是从标题构造的，因此这有助于确保自动构造的锚点链接是直观和清晰的。

例如，代替

## Foo
### Summary
### Example
## Bar
### Summary
### Example

首选

## Foo
### Foo summary
### Foo example
## Bar
### Bar summary
### Bar example

为标题添加间距

首选在 # 之后添加空格并在之前和之后添加换行符

...text before.

## Heading 2

Text after...

缺少空格会使源代码中的阅读更加困难

...text before.

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

使用单个 H1 标题

使用一个 H1 标题作为文档的标题。 后续标题应为 H2 或更深级别。 有关更多信息，请参见 文档布局。

标题和大写

请遵循 Google 开发者文档风格指南中的大小写指南。

列表

对于长列表，使用惰性编号

Markdown 非常智能，可以使生成的 HTML 正确呈现你的编号列表。 对于可能更改的较长列表，尤其是较长的嵌套列表，请使用“惰性”编号

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

但是，如果列表很小并且你不希望更改它，请首选完全编号的列表，因为它在源代码中更易于阅读

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

嵌套列表间距

嵌套列表时，编号列表和项目符号列表均使用 4 个空格的缩进

1.  Use 2 spaces after the item number, so the text itself is indented 4 spaces.
    Use a 4-space indent for wrapped text.
2.  Use 2 spaces again for the next item.

*   Use 3 spaces after a bullet, so the text itself is indented 4 spaces.
    Use a 4-space indent for wrapped text.
    1.  Use 2 spaces with numbered lists, as before.
        Wrapped text in a nested list needs an 8-space indent.
    2.  Looks nice, doesn't it?
*   Back to the bulleted list, indented 3 spaces.

以下方法可行，但非常混乱

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

即使没有嵌套，使用 4 个空格的缩进也可以使换行文本的布局保持一致

*   Foo,
    wrapped with a 4-space indent.

1.  Two spaces for the list item
    and 4 spaces before wrapped text.
2.  Back to 2 spaces.

但是，当列表很小、未嵌套且为单行时，两种类型的列表都可以使用一个空格

* Foo
* Bar
* Baz.

1. Foo.
2. Bar.

代码

内联

`反引号` 指定将按字面意义呈现的 内联代码。 将它们用于简短的代码引用、字段名称等

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 处理，例如虚假路径或示例 URL，这会导致错误的自动链接，请将其包装在反引号中

An example Markdown shortlink would be: `Markdown/foo/Markdown/bar.md`

An example query might be: `https://www.google.com/search?q=$TERM`

代码块

对于超过一行的代码引用，请使用围栏式代码块

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

声明语言

最佳实践是显式声明语言，以便语法突出显示器和下一个编辑器都不必猜测。

使用围栏式代码块而不是缩进式代码块

四空格缩进也被解释为代码块。 但是，我们强烈建议对所有代码块进行围栏式编码。

缩进代码块有时在源代码中看起来更干净，但它们有几个缺点

• 你无法指定语言。 某些 Markdown 功能与语言说明符相关联。
• 代码块的开头和结尾不明确。
• 在代码搜索中更难搜索缩进的代码块。

You'll need to run:

    bazel run :thing -- --foo

And then:

    bazel run :another_thing -- --bar

And again:

    bazel run :yet_again -- --baz

转义换行符

因为大多数命令行代码段旨在直接复制并粘贴到终端中，所以最佳做法是转义任何换行符。 在行尾使用单个反斜杠

```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 链接使用显式路径。 例如

[...](/path/to/other/markdown/page.md)

你无需使用整个限定的 URL

[...](https://bad-full-url.example.com/path/to/other/markdown/page.md)

除非在同一目录中，否则避免使用相对路径

相对路径在同一目录中是相当安全的。 例如

[...](other-page-in-same-dir.md)
[...](/path/to/another/dir/other-page.md)

如果你需要使用 ../ 指定其他目录，请避免使用相对链接

[...](../../bad/path/to/another/dir/other-page.md)

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

Markdown 链接语法允许你设置链接标题。 明智地使用它。 用户通常不阅读文档； 他们会扫描文档。

链接引人注目。 但是，将你的链接标题为“此处”、“链接”或简单地复制目标 URL 并不能告诉匆忙的读者任何信息，并且是空间的浪费

DO NOT DO THIS.

See the Markdown guide for more info: [link](markdown.md), or check out the
style guide [here](/styleguide/docguide/style.html).

Check out a typical test result:
[https://example.com/foo/bar](https://example.com/foo/bar).

而是自然地编写句子，然后返回并使用链接包装最合适的短语

See the [Markdown guide](markdown.md) for more info, or check out the
[style guide](/styleguide/docguide/style.html).

Check out a
[typical test result](https://example.com/foo/bar).

参考

对于长链接或图像 URL，你可能希望将链接使用与链接定义分开，如下所示

See the [Markdown style guide][style], which has suggestions for making docs more
readable.

[style]: http://Markdown/corp/Markdown/docs/reference/style.md

对长链接使用参考链接

如果链接的长度会影响周围文本的可读性（如果内联），请使用参考链接。 参考链接使得在源文本中查看链接的目标变得更加困难，并添加了额外的语法。

在此示例中，参考链接的使用是不合适的，因为链接不够长，不会中断文本的流程

DO NOT DO THIS.

The [style guide][style_guide] says not to use reference links unless you have
to.

[style_guide]: https://google.com/Markdown-style

只需内联即可

https://google.com/Markdown-style says not to use reference links unless you have to.

在此示例中，链接目标足够长，因此使用参考链接是有意义的

The [style guide] says not to use reference links unless you have to.

[style guide]: https://docs.google.com/document/d/13HQBxfhCwx8lVRuN2Wf6poqvAfVeEXmFVcawP5I6B3c/edit

在表格中更频繁地使用引用链接。 保持表格内容简短尤为重要，因为 Markdown 不提供在单元格表格中跨多行换行的功能，并且较小的表格更易于阅读。

例如，此表格的可读性因内联链接而降低

DO NOT DO THIS.

Site                                                             | Description
---------------------------------------------------------------- | -----------------------
[site 1](http://google.com/excessively/long/path/example_site_1) | This is example site 1.
[site 2](http://google.com/excessively/long/path/example_site_2) | This is example site 2.

请改用引用链接来保持行长度易于管理

Site     | Description
-------- | -----------------------
[site 1] | This is example site 1.
[site 2] | This is example site 2.

[site 1]: http://google.com/excessively/long/path/example_site_1
[site 2]: http://google.com/excessively/long/path/example_site_2

使用参考链接以减少重复

如果在文档中多次引用同一链接目标，请考虑使用引用链接以减少重复。

在第一次使用后定义参考链接

我们建议将引用链接定义放在下一个标题之前，即它们首次使用的部分的末尾。 如果你的编辑器对它们应该放在哪里有自己的看法，不要与之抗争； 工具总是会赢的。

我们将“节”定义为两个标题之间的所有文本。 将引用链接视为脚注，并将当前节视为当前页面。

这种安排可以轻松地在源代码视图中找到链接目标，同时保持文本流免受混乱。 在包含大量引用链接的长文档中，它还可以防止文件底部的“脚注过多”，从而难以挑选出相关的链接目标。

此规则有一个例外：在多个节中使用的引用链接定义应放在文档末尾。 这可以避免在更新或移动节时出现悬空链接。

在以下示例中，引用定义远离其最初使用的地方，这使得文档更难阅读

# Header FOR A BAD DOCUMENT

Some text with a [link][link_def].

Some more text with the same [link][link_def].

## Header 2

... lots of text ...

## Header 3

Some more text using a [different_link][different_link_def].

[link_def]: http://reallyreallyreallylonglink.com
[different_link_def]: http://differentreallyreallylonglink.com

请将其放在首次使用后的标题之前

# Header

Some text with a [link][link_def].

Some more text with the same [link][link_def].

[link_def]: http://reallyreallyreallylonglink.com

## Header 2

... lots of text ...

## Header 3

Some more text using a [different_link][different_link_def].

[different_link_def]: http://differentreallyreallylonglink.com

图片

参见 图片语法。

谨慎使用图片，并首选简单的屏幕截图。 本指南的设计理念是，纯文本可以让用户更快地进行沟通，减少读者的注意力分散和作者的拖延。 但是，有时显示你的意思非常有用。

• 当展示给读者某些东西比描述它更容易时，请使用图片。 例如，使用图片解释如何浏览 UI 通常比文本更容易。
• 请务必提供适当的文本来描述你的图片。 看不见的读者无法看到你的图片，仍然需要理解内容！ 请参阅下面的替代文本最佳实践。

表格

在有意义时使用表格：用于需要快速扫描的表格数据的表示。

当你的数据可以很容易地在列表中呈现时，避免使用表格。 列表在 Markdown 中更容易编写和阅读。

例如

DO NOT DO THIS

Fruit  | Metrics      | Grows on | Acute curvature    | Attributes                                                                                                  | Notes
------ | ------------ | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------
Apple  | Very popular | Trees    |                    | [Juicy](http://cs/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet               | Apples keep doctors away.
Banana | Very popular | Trees    | 16 degrees average | [Convenient](http://cs/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes. Don't you? See the [design doc][banana_v2] for the newest hotness in bananiels.

此表说明了一些典型问题

• 分布不良：几列在行之间没有差异，有些单元格是空的。 这通常表明你的数据可能不会从表格显示中受益。

• 不平衡的维度：相对于列，行数很少。 当此比率在任一方向上不平衡时，表格就变成了一个不灵活的文本格式。

• 一些单元格中漫无边际的散文。 表格应该一目了然地讲述一个简洁的故事。

列表和子标题有时足以呈现相同的信息。 让我们以列表形式查看此数据

## Fruits

Both types are highly popular, sweet, and grow on trees.

### Apple

*   [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
*   Firm

Apples keep doctors away.

### Banana

*   [Convenient](http://cs/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
*   Soft
*   16 degrees average acute curvature.

Contrary to popular belief, most apes prefer mangoes. Don't you?

See the [design doc][banana_v2] for the newest hotness in bananiels.

列表形式更加宽敞，因此在这种情况下，读者更容易找到她感兴趣的内容。

但是，有时表格是最佳选择。 当你有

• 跨两个维度相对均匀的数据分布。
• 许多具有不同属性的并行项目。

在这些情况下，表格格式正是你所需要的。 事实上，一个紧凑的表格可以提高可读性

Transport        | Favored by     | Advantages
---------------- | -------------- | -----------------------------------------------
Swallow          | Coconuts       | [Fast when unladen][airspeed]
Bicycle          | Miss Gulch     | [Weatherproof][tornado_proofing]
X-34 landspeeder | Whiny farmboys | [Cheap][tosche_station] since the XP-38 came out

[airspeed]: http://google3/airspeed.h
[tornado_proofing]: http://google3/kansas/
[tosche_station]: http://google3/power_converter.h

请注意，使用了引用链接来保持表格单元格的可管理性。

强烈建议使用 Markdown 而不是 HTML

请尽可能首选标准 Markdown 语法，避免使用 HTML hack。 如果你似乎无法完成你想要做的事情，请重新考虑你是否真的需要它。 除了大型表格外，Markdown 已经满足了几乎所有的需求。

每一段 HTML hacking 都会降低我们 Markdown 语料库的可读性和可移植性。 这反过来又限制了与其他工具集成的有用性，这些工具可能会将源代码呈现为纯文本或进行渲染。 参见哲学。

Gitiles 不渲染 HTML。

1. 如果页面首次显示时可见，则内容“位于首屏上方”。 如果内容在用户在计算机上向下滚动页面或实际展开诸如报纸之类的文档之前是隐藏的，则内容“位于首屏下方”。 ↩

本网站是开源的。 改进此页面。