譯者：nbztx
聯系方式：nbztx@126.com
Markdown的出色之處主要在于能夠使用純文本書寫并且得到一流的格式化輸出結果，
我們想要平衡以下三個目標：
- 源代碼具有良好的可讀性和可移植性
- Markdown文件隨時間推移、在團隊之間的可維護性
- 語法簡單且容易記憶
內容：
文檔標題
一般情況下，大多數文檔會采用下面幾種布局：
# Document Title
Short introduction.
[TOC]
## Topic
Content.
## See also
* https://link-to-more-info
# Document Title: 第一個標題應當是一個一級標題，并且應該盡可能和文件名稱保持一致。第一個一級標題會被用作頁面標題。author: 可選項。如果你想要說明對文檔的所有權或者它是你的得意之作，就把你自己放到標題下吧，雖然版本修訂記錄通常就足夠說明這一點了。Short introduction: 1~3句能夠概括整個主題的話。想象你自己是一個完全的新手，剛剛接觸你寫的《Java從入門到精通》，需要了解那些你自己認為理所應當的最基本的前置知識，比如“什么是Java”、“為什么我要學習Java”。[TOC]: 用來生成目錄。## Topics: 你剩下的標題應該從二級標題開始開始使用。## See also: 在底部為想了解更多相關知識或沒有找到所需知識的用戶放置各種鏈接。
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).
通常在長鏈接前新起一行有利于可讀性，并且能夠最小化鏈接的溢出。
Lorem ipsum dolor sit amet. See the
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
for details.
尾隨空格
不要使用尾隨空格，用尾隨的反斜杠代替。
Don't use trailing whitespace, use a trailing backslash.
雖然 CommonMark spec 判定一行末尾的兩個空格等同于插入一個“<br />”標簽，但很多文件系統會有提交前的尾部空格檢查，很多IDE也會把尾部空格清理掉。
最好的方法是完全避免使用“<br />”的需要，Markdown用新行表示段落的標簽，習慣它。
標題
ATX風格的標題
## Heading 2
含有“=”或“-”下劃線的標題維護起來會很討厭，而且和其他標題語法不兼容。用戶不知道“---”的意思是H1還是H2。
Heading - do you remember what level? DO NOT DO THIS.
---------
標題中的間隔
請在“#”后加空格，并和上下文保持間隔：
...text before.
# 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.
嵌套列表間距
嵌套列表時，對數字開頭的列表和星號開頭的列表都使用四個空格的縮進：
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.
代碼
單行代碼
`反引號`定義了單行代碼，并且會逐字逐句呈現所有包含的文本，用它來進行簡短的代碼和字段的引用：
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`!
Backticks are the most common approach for "escaping" Markdown metacharacters;
in most situations where escaping would be needed, code font just makes sense
anyway.
代碼塊
代碼超過一行時，請使用代碼塊：
<pre>
def Foo(self, bar):
self.bar = bar
</pre>
語言聲明
分開進行語言聲明是最好的，這樣無論語法高亮器還是另外的文本編輯器都不需要瞎猜。
縮進代碼塊有時會更清晰易讀
四個空格的縮進也會被翻譯成代碼塊，這能使源碼變得更加清晰易讀，缺點是無法區分語言。我們建議在寫較短的片段時這樣做：
You'll need to run:
bazel run :thing -- --foo
And then:
bazel run :another_thing -- --bar
And again:
bazel run :yet_again -- --baz
避免換行
由于大多數命令行代碼片段要被直接復制粘貼進終端，最好的方法是避免任何換行，在行尾加一個反斜杠即可：
<pre>
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
</pre>
列表內嵌代碼塊
如果你要在列表中內嵌代碼塊，使用縮進來確保它不會破壞列表：
* Bullet.
```c++
int foo;
```
* Next bullet.
你也可以用4個空格來創建內嵌代碼塊，只需要從列表縮進處額外加4個空格：
* Bullet.
int foo;
* Next bullet.
鏈接
Long links make source Markdown difficult to read and break the 80 character
wrapping。盡可能縮短你的鏈接。
使用具有提示性的鏈接標題
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.
正確的做法應該是：先按文章的意思寫好句子，再回過頭找出最合適的短語，把它標記成鏈接。
See the [syntax guide](syntax_guide.md) for more info.
Or, check out the [style guide](style_guide.md).
圖像
盡可能少用圖像，多使用簡單的截圖。這一建議的意思是純文本能夠讓用戶更快了解到信息的內容，而減少分心和來自作者的拖延。
盡管如此，有時候圖片對于表明你的意思還是很有幫助的。
查閱 image syntax 了解更多。
優先使用列表
任何Markdown中的表格都應該盡可能小，復雜的、大型的表格在源碼中讀起來很困難，接下來想修改會更痛苦。
Fruit | Attribute | Notes
--- | --- | --- | ---
Apple | [Juicy](http://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
DO NOT DO THIS
列表和子標題通常足夠你用來呈現相同的信息，不那么緊湊，卻要容易編輯得多：
## Fruits
### Apple
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet
Apples keep doctors away.
### Banana
* [Convenient](http://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語法
盡可能使用標準Markdown語法，避免嵌入使用HTML。如果你無法實現你想要的效果，再好好考慮一下你是否真的需要它。因為除了大型表格，Markdown幾乎已經可以滿足任何需求。
任何HTML或Javascript的嵌入都會降低可讀性和可移植性，這反過來會限制文檔和其它工具整合的有效性，
which may either present the source as plain text or render it. See
Philosophy.
Gitiles does not render HTML.
