譯者：nbztx
聯(lián)系方式：nbztx@126.com
Markdown的出色之處主要在于能夠使用純文本書寫并且得到一流的格式化輸出結(jié)果，
我們想要平衡以下三個目標(biāo)：
- 源代碼具有良好的可讀性和可移植性
- Markdown文件隨時間推移、在團(tuán)隊之間的可維護(hù)性
- 語法簡單且容易記憶
內(nèi)容：
文檔標(biāo)題
一般情況下，大多數(shù)文檔會采用下面幾種布局：
# Document Title
Short introduction.
[TOC]
## Topic
Content.
## See also
* https://link-to-more-info
# Document Title: 第一個標(biāo)題應(yīng)當(dāng)是一個一級標(biāo)題，并且應(yīng)該盡可能和文件名稱保持一致。第一個一級標(biāo)題會被用作頁面標(biāo)題。author: 可選項。如果你想要說明對文檔的所有權(quán)或者它是你的得意之作，就把你自己放到標(biāo)題下吧，雖然版本修訂記錄通常就足夠說明這一點了。Short introduction: 1~3句能夠概括整個主題的話。想象你自己是一個完全的新手，剛剛接觸你寫的《Java從入門到精通》，需要了解那些你自己認(rèn)為理所應(yīng)當(dāng)?shù)淖罨镜那爸弥R，比如“什么是Java”、“為什么我要學(xué)習(xí)Java”。[TOC]: 用來生成目錄。## Topics: 你剩下的標(biāo)題應(yīng)該從二級標(biāo)題開始開始使用。## See also: 在底部為想了解更多相關(guān)知識或沒有找到所需知識的用戶放置各種鏈接。
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 />”標(biāo)簽，但很多文件系統(tǒng)會有提交前的尾部空格檢查，很多IDE也會把尾部空格清理掉。
最好的方法是完全避免使用“<br />”的需要，Markdown用新行表示段落的標(biāo)簽，習(xí)慣它。
標(biāo)題
ATX風(fēng)格的標(biāo)題
## Heading 2
含有“=”或“-”下劃線的標(biāo)題維護(hù)起來會很討厭，而且和其他標(biāo)題語法不兼容。用戶不知道“---”的意思是H1還是H2。
Heading - do you remember what level? DO NOT DO THIS.
---------
標(biāo)題中的間隔
請在“#”后加空格，并和上下文保持間隔：
...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.
而對于比較短的、很少修改的有序列表，按順序標(biāo)號更好，因為這樣源碼讀起來更加容易：
1. Foo.
2. Bar.
3. Baz.
嵌套列表間距
嵌套列表時，對數(shù)字開頭的列表和星號開頭的列表都使用四個空格的縮進(jìn)：
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.
即使沒有嵌套，使用四個空格的縮進(jìn)也會讓包含文本的布局顯得更加連續(xù)：
* Foo,
wrapped.
1. 2 spaces
and 4 space indenting.
2. 2 spaces again.
當(dāng)然，如果列表規(guī)模很小、沒有嵌套、只有單行，那么單個空格也足夠了：
* Foo
* Bar
* Baz.
1. Foo.
2. Bar.
代碼
單行代碼
`反引號`定義了單行代碼，并且會逐字逐句呈現(xiàn)所有包含的文本，用它來進(jìn)行簡短的代碼和字段的引用：
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>
語言聲明
分開進(jìn)行語言聲明是最好的，這樣無論語法高亮器還是另外的文本編輯器都不需要瞎猜。
縮進(jìn)代碼塊有時會更清晰易讀
四個空格的縮進(jìn)也會被翻譯成代碼塊，這能使源碼變得更加清晰易讀，缺點是無法區(qū)分語言。我們建議在寫較短的片段時這樣做：
You'll need to run:
bazel run :thing -- --foo
And then:
bazel run :another_thing -- --bar
And again:
bazel run :yet_again -- --baz
避免換行
由于大多數(shù)命令行代碼片段要被直接復(fù)制粘貼進(jìn)終端，最好的方法是避免任何換行，在行尾加一個反斜杠即可：
<pre>
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
</pre>
列表內(nèi)嵌代碼塊
如果你要在列表中內(nèi)嵌代碼塊，使用縮進(jìn)來確保它不會破壞列表：
* Bullet.
```c++
int foo;
```
* Next bullet.
你也可以用4個空格來創(chuàng)建內(nèi)嵌代碼塊，只需要從列表縮進(jìn)處額外加4個空格：
* Bullet.
int foo;
* Next bullet.
鏈接
Long links make source Markdown difficult to read and break the 80 character
wrapping。盡可能縮短你的鏈接。
使用具有提示性的鏈接標(biāo)題
Markdown鏈接語法允許你像HTML一樣設(shè)置鏈接，但你要正確地使用它。
當(dāng)讀者快速瀏覽像“l(fā)ink”或“here”這樣的鏈接標(biāo)題時，他們完全得不到任何信息，這只是一種對空間的浪費。
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.
正確的做法應(yīng)該是：先按文章的意思寫好句子，再回過頭找出最合適的短語，把它標(biāo)記成鏈接。
See the [syntax guide](syntax_guide.md) for more info.
Or, check out the [style guide](style_guide.md).
圖像
盡可能少用圖像，多使用簡單的截圖。這一建議的意思是純文本能夠讓用戶更快了解到信息的內(nèi)容，而減少分心和來自作者的拖延。
盡管如此，有時候圖片對于表明你的意思還是很有幫助的。
查閱 image syntax 了解更多。
優(yōu)先使用列表
任何Markdown中的表格都應(yīng)該盡可能小，復(fù)雜的、大型的表格在源碼中讀起來很困難，接下來想修改會更痛苦。
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
列表和子標(biāo)題通常足夠你用來呈現(xiàn)相同的信息，不那么緊湊，卻要容易編輯得多：
## 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
優(yōu)先使用Markdown語法
盡可能使用標(biāo)準(zhǔn)Markdown語法，避免嵌入使用HTML。如果你無法實現(xiàn)你想要的效果，再好好考慮一下你是否真的需要它。因為除了大型表格，Markdown幾乎已經(jīng)可以滿足任何需求。
任何HTML或Javascript的嵌入都會降低可讀性和可移植性，這反過來會限制文檔和其它工具整合的有效性，
which may either present the source as plain text or render it. See
Philosophy.
Gitiles does not render HTML.
