Markdown语法 (中文版)
Markdown語法
Markdown是一種可以使用普通文本編輯器編寫的標記語言，通過類似HTML的標記語法，它可以使普通文本內容具有一定的格式。
Markdown具有一系列衍生版本，用于擴展Markdown的功能（如表格、腳注、內嵌HTML等等），這些功能原初的Markdown尚不具備，它們能讓Markdown轉換成更多的格式，例如LaTeX，Docbook。Markdown增強版中比較有名的有Markdown Extra、MultiMarkdown、 Maruku等。這些衍生版本要么基于工具，如Pandoc；要么基于網站，如GitHub和Wikipedia，在語法上基本兼容，但在換行等細節上也有改動。
綜述
宗旨
Markdown致力于盡可能地易讀易寫.
然而, 易讀性才是重中之重. 一個Markdown格式的文檔應該就像普通文本一樣容易(排版)打印, 而不是用各種標簽和格式指令來標記. 現有的一些文本-HTML過濾器(text-to-HTML filters)對Markdown的語法有著重要的影響, 包括Setext, atx, Textlie, reStructuredText, Grutatext, 和EtText, 然而Markdown語法最大的靈感則來自于純文本郵件的格式.
鑒于此, Markdown的語法完全由標點字符組成, 這些字符經過精心挑選, 就是為了能夠讓它們起到它們看起來應該起的作用. 比如一個單詞兩邊的星號看起來就像emphasis. Markdown(語法的)列表就應該看起來就像是(實際的)列表. 如果你此前使用的email, 那么即使是Markdown的引用也能夠看起來就像是實際的對一段文字的引用一樣.
內聯HTML
Markdown的語法只有一個目的: 用來作為一種專門為web寫作設計的格式.
Markdown不是為了取代HTML, 也不是為了接近HTML. 它的語法非常少, 僅對應著HTML標簽的一個很小的子集. 創造Markdown的目標不是為了讓插入HTML標簽更容易. 就我個人來說, HTML標簽已經很簡單了. Markdown的理念是為了讓閱讀, 編寫, 編輯簡單文本更加容易. HTML是一個印刷格式, 而Markdown是一個寫作格式. 因此Markdown格式的語法只用于處理能夠轉變為純文本的一些功能.
對于那些不包括在Markdown語法之內的標記, 你可以直接使用HTML標簽, 而不用在從Markdown語法轉換到HTML之前做任何說明或者分隔. 直接使用HTML標簽就行了.
唯一的限制是當你使用HTML塊元素的時候-例如<div>,<table>,<pre>,<p>等-必須和上下文用空行分開, 并且開始標記和結束標記不能使用tab或者空格縮進(否則會被當做代碼段). Markdown能夠智能地識別出何時不在HTML塊級元素添加額外的(不必要)的<p>.
例如, 為了向一片Markdown文本添加一個HTML表格:
This is a regular paragraph.
<table>
<tr>
<td>Foo</td>
</tr>
</table>
This is another regular paragraph.
注意到在HTML塊元素標簽里面Markdown格式的語法不會被解釋, 例如你不能在HTML塊元素里面使用Markdown風格的強調*emphasis*.
內聯HTML元素-例如<span>,<cite>或者<del>-可以在Markdown段落, 列表項或者頭部中的任何地方. 你甚至可以使用HTML標簽代替Markdown的格式. 例如你可以用HTML的<a>或者<img>標簽代替Markdown的超鏈接或者圖片語法.
與HTML塊元素不同的是, 內聯元素內的Markdown語法會被解釋處理.
特殊字符的自動轉義
在HTML中, 有兩個字符需要特殊對待:<和&.<左尖括號表示標簽的開始,&表示HTML字符實體. 如果你想使用它們的字面常量, 就必須把它們轉義成實體, 例如<和&.
對于web作家來說字符&尤其令人苦惱. 如果你想寫一個'AT&T', 你就必須寫成'AT&T'. 甚至你需要對URL中的字符&進行轉義. 因此如果你要鏈接到:
http://images.google.com/images?num=30&q=larry+bird
你必須把URL編碼成下面這樣:
http://images.google.com/images?num=30&q=larry+bird
然后設置為<a>標簽href屬性值. 毋庸置疑這很容易忘記, 并且最容易稱為一個編寫良好的站點中唯一一個校驗錯誤的地方.
Markdown允許你自然地使用這個字符, 在需要轉義的時候替你完成這些任務. 如果你需要在HTML實體里面插入一個&, 那么Markdown不會做任何轉換; 否則Markdown會將它轉換成&.
所以如果你要包含一個copyright符號在你的文本中, 你可以寫成
©
Markdown將保持它的原樣. 但是如果你想寫一個:
AT&T
Markdown就會把它轉換成:
AT&T
類似地, 由于Markdown支持內聯HTML, 如果你用一對尖括號作為HTML標簽的分隔符, Markdown則會保持尖括號的原樣; 但是如果你要寫一個:
4<5
Markdown就會把它轉換成:
4<5
不管怎樣, 在Markdown代碼片段和塊元素中, 尖括號和符號&始終會被自動編碼. 這就使得使用Markdown編寫HTML代碼變得很容易. (這和原生HTML代碼中糟糕的格式恰好相反, 因為對于每一個代碼中的<,>和&你都必須要手動轉義).
...
塊級元素
段落與換行
一個段落是由一個或多個連續的行組成的, 段與段之間通過一個或多個空行分隔. (除了空格和tab外不包含其他任何字符的行都被視為空行.) 普通的行不能用空格或者tab縮進.
上面"一個或多個連續的行"所暗含的意思就是, Markdown支持"hard-wrapped"文本段落. 這跟大部分把每一個換行符轉換成一個HTML<br />標簽的text-to-HTML格式化程序(包括Movable Type's的"轉換換行符"選項)有著顯著不同.
當你確實需要使用Markdown插入一個<br />換行標簽的時候, 只要在行結尾添加兩個或者多個空格再加一個回車就可以了.
這的確需要額外的功夫才能插入一個<br />, 但是過分簡化的"每個換行符就是一個HTML<br />標簽"的規則不太適用于Markdown. Markdown基于email風格的塊引用和列表項最好用-并且更易讀-當你用硬換行格式化的時候.
HEADERS頭部
Markdown支持兩種風格的頭部, [Setext][1]和[atx][2].
Setext風格的頭部是使用雙等號的下劃線(一級頭部)和使用破折號的下劃線(二級頭部). 例如:
This is an H1 ============= This is an H2 -------------
任意數量的=和-都可以.
Atx風格的頭部是在每一行的開頭添加1到6個井號字符#, 對應著1級到6級頭部. 例如:
#This is an H1 ##This is an H2 ######This is an H6
你可以選擇帶有"結束"標記的atx頭部. 這純粹是為了美觀-如果你覺得這會讓你的Markdown代碼更加易讀.#符號的數目甚至都不用與頭部的開始標記數量相同.(開始#號的數量用于表示頭部的級別):
#This is an H1 # ##This is an H2 ## ###This is an H3 ######
引用
Markdown使用email風格的字符>作為引用. 如果你熟悉email文本里面的引用, 那你就會知道怎樣在Markdown里面創建一個引用. 如果你手動排版固定文本并且在每一行開頭前面加上一個>, 那么看起來是最美觀的:
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. > > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse > id sem consectetuer libero luctus adipiscing.
當然Markdown允許你偷懶, 你只需在一段排版好的文本的第一行添加一個>:
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
引用可以通過添加額外的>實現引用嵌套(例如, 一個引用中的引用):
> This is the first level of quoting. > > > This is nested blockquote. > > Back to the first level.
引用可以包含其他的Markdown元素, 包括頭部, 列表和代碼塊:
>##This is a header
>
>1. This is the first list item
>2. This is the second list item
>
>Here's some example code
>
> return shell_exec("echo $input | $markdown_script");
任何一個不錯的文本編輯器都應該能夠簡化email風格的引用. 例如通過BBEdit你可以選定一段文本然后從文本菜單選擇升級引用級別.
列表
Markdown支持有序(編號的)列表和無序列表.
無序列表使用星號(*), 加號(+)和減號(-)-可以交替使用-來作為列表標記:
* Red * Green * Blue
等同于:
+ Red + Green + Blue
和
- Red - Green - Blue
有序列表使用數字緊跟一個句號.:
1. Bird 2. McHale 3. Parish
重要的一點是, 你用來標記列表項的實際數字并不會影響Markdown所生成的HTML列表格式. 上面使用Markdown生成的HTML列表是:
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>`
如果你像這樣編寫Markdown:
1. Bird 1. Mchale 1. Parish
甚至這樣:
3. Bird 1. Mchale 8. Parish
都能生成完全一樣的HTML. 關鍵在于, 如果你想, 你可以使用有序數字來標記Markdown列表, 這樣Markdown源文本里面的數字就能和輸出的HTML列表項數字保持一致了. 但是如果你想偷懶, 也可以不強制這樣做.
如果你偷懶（不使用有序數字來標記Markdown有序列表), 你仍然應該從1開始標記列表項. 在未來Markdown有可能會支持有序列表的start屬性.
一般情況下列表標記從左邊開始, 也有可能縮進最多三個空格. 列表標記之后必須緊跟至少一個空格或者一個tab.
為了讓列表更加美觀, 你可以使用hanging(對齊的)縮進來包裝列表項:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
如果你想偷懶, 也可以這樣寫:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
如果你用空行分隔列表項, Markdown輸出的HTML代碼會將列表項用
標簽包裝起來. 例如:
* Bird * Magic
將被轉換成HTML:
<ul>
<li>Bird</li>
<li>Magic</li>
<ul>
但是下面的:
* Bird * Magic
將被轉換成:
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
列表項可能會有多個段落, 每個子段落必須用四個空格或者一個tab縮進:
1. This is a list item with two paragraphs. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
對子段落中的每一行使用縮進可以讓Markdown文本更加美觀. 但是Markdown任然允許你偷懶:
* This is a list item with two paragraphs.
This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.
* Another item in the same list.
為了在列表項內部插入一個引用, 則需要對引用的>分隔符縮進:
* A list item with a blockquote:
> This is a blockquote
> inside a list item
要在列表項里插入代碼段, 那么需要對代碼段進行兩次縮進 - 8個空格或者2個tab:
* A list item with a code block:
public class Test() {
public static void main(String[] args) {
System.out.println("Hello Markdown");
}
}
有時候會不經意間導致生成Markdown列表, 比如這種寫法:
1986. What a great season.
換句話說, 在任一段開頭如果如果恰好包含一個數字-句號-空格序列模式就會生成一個列表項. 你可以在句號前面加一個斜線轉義來避免這種情況:
1986. What a great season.
代碼塊
格式化的代碼塊通常用在與編程或者標記文本源碼的寫作中. 與格式化普通段落不同的是, 我們希望代碼塊里的行保持原有格式. Markdown將代碼塊同時用<pre>和<code>標簽包裝起來.
要在Markdown里面生成代碼塊, 只需要對代碼塊中的每一行縮進4個空格或者1個tab就可以了. 例如下面這一段文本:
This is a normal paragraph;
This is a code block.
Markdown會生成:
<p>This is a normal paragraph;</p> <pre><code>This is a code block </code></pre>
一級縮進-4個空格或1個tab-將會從代碼段中被移除. 例如:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
將會被轉換成:
<p>Here is an example of AppleScript<p>
<pre><code>tell application "Foo"
beep
end tell
</code></pre>
一個代碼段以一個未縮進的行結束(或者文章結尾).
在一個代碼段內,&,<和>將被自動轉換為HTML實體. 這就使得在Markdown里包含HTML代碼段變得非常容易- 粘貼然后縮進, Markdown會自動處理&,<和>的編碼. 例如:
<div class="footer">
© 2004 Foo Corporation
</div>
將被轉換成:
<pre><code><pre><div class="footer">
&copy; 2004 Foo Corporation
</div>
</code></pre>
代碼段內的普通Markdown語法不會被處理, 例如代碼段內的星號*就是字面量星號*. 這就意味著使用Markdown去編寫Markdown的語法很容易.
水平線
在一行內輸入(且只能是)三個或以上的*,-或_就能生成一個水平線(<hr />). 當然你可以在連續的-或*之間插入空格. 下面的每一行都將生成一個水平線:
* * * *** ***** - - - __________________________________
...
內聯元素
超鏈接
Markdown支持兩種風格的鏈接: 內聯式(inline)和引用式(reference).
這兩種風格都要求超鏈接的文本內容用中括號[]分隔.
在中括號的結尾使用一對圓括號()就能創建鏈接地址, 圓括號內部就是要指向的鏈接地址, 如果你想為鏈接創建標題那么可以在鏈接URL之后輸入一段用雙引號包含的文本. 例如:
This is [an example](https://ayningcao.github.io "My Github") inline link [This link](https://ayningcao.github.io) has no title attribute
將會生成:
<p>This is <a title="My Github"> an example</a> inline link.</p> <p><a >This link</a> has no title attribute.</p>
如果是鏈接是指向本地資源你也可以使用相對路徑:
See my [About](/about/) apge for details.
引用式的鏈接是在超鏈接文本后面添加一對中括號, 中括號的內容是目標URL的標簽:
This is [an example][id] reference-style link.
你也可以在兩對中括號之間插入一個空格.
然后你可以在文檔其他任何地方定義鏈接的標簽:
[id]: http://ayningcao.github.io/ "title"
這個引用式鏈接的格式是:
開頭是一個中括號[], 中括號里面包含鏈接ID(從左開始可以包含最多三個空格作為縮進);
然后跟著一個冒號:;
然后是一個或多個空格;
鏈接的實際URL;
最后是一個可選的鏈接標題, 標題用雙引號, 單引號或者圓括號包圍.
下面這三個鏈接定義是等價的:
[Github]: http://github.com/ "github.com" [Github]: http://github.com/ 'github.com' [Github]: http://github.com/ (github.com)
注意: 在Markdown.pl 1.0.1版本里有一個bug會使得用單引號對title定界出現異常.
也可以用尖括號來包含鏈接URL：
[id]: <http://github.com> "Github"
如果URL很長影響可讀性, 你也可以把鏈接title放到下一行, 并用額外的空格或者tab來對齊標題:
[id]: <https://ayningcao.github.com/index.html>
"My Own Github"
鏈接定義只在Markdown處理期間用于創建鏈接, 并不會輸出到最終的HTML.
鏈接定義可以包含字母, 數字, 空格和標點符號 - 并且大小寫不敏感. 比如下面的兩個鏈接定義是等價的:
[link text][a] [link text][A]
在鏈接的文本本身就是鏈接名的情況下, 可以通過隱式鏈接名這種快捷方式省略鏈接名. 只要用一對空中括號-比如, 通過單詞Google連接到google.com網站, 你可以直接這樣寫:
[Google][]
然后定義鏈接:
[Google]: http://google.com
由于鏈接名可能會包含空格, 因此你還可以這樣寫快捷方式:
Visit [Daring Fireball][] for more information.
然后定義鏈接:
[Daring Fireball]: http://daringfireball.net/
鏈接定義可以被放在Markdown文本中的任何位置. 我個人更加傾向于把他們放在被引用的段落后面. 當然你也可以把他們全部放在文檔的末尾, 就像是腳注一樣.
這里有一個引用式鏈接的例子:
I get 10 times more traffic from [Goole][1] than from [Yahoo][2] or [MSN][3]. [1]: http://google.com/ "Google" [2]: http://search.yahoo.com/ "Yahoo Search" [3]: http://search.msn.com/ "MSN Search"
通過隱式鏈接名快捷方式你可以這樣創建:
I get 10 times more traffic from [Google][] than from [Yahoo][] or [MSN][]. [google]: http://google.com/ "Google" [yahoo]: http://search.yahoo.com/ "Yahoo Search" [msn]: http://search.msn.com/ "MSN Search"
上面兩種方式都會生成下面這種HTML代碼:
<p>I get 10 times more traffic from <a title="Google">Google</a> than from <a title="Yahoo Search">Yahoo</a> or <a title="MSN Search">MSN</a>.</p>
我們可以對比下使用Markdown內聯風格的鏈接寫法:
I get 10 times more traffic from [Google](http://google.com/ "Google") than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or [MSN](http://search.msn.com/ "MSN Search").
引用式的鏈接寫法關鍵點不在于更易寫, 而是它會使得你的Markdown原文本明顯更加易讀. 對比以上兩個例子: 使用引用式鏈接, 段落本身只有81個字符, 而內聯方風格要176個字符, 而原始HTML代碼則需要234個字符, 而且HTML標簽比文本內容竟然都要多.
通過Markdown的引用式鏈接可以使得源文檔格式盡可能與瀏覽器里渲染出的最終的樣式接近. 通過將與文本無關的標記相關的元數據移出段落, 就可以不用打斷正常的段落敘述(而將精力集中在文本本身的內容).
強調(EMPHASIS)
Markdown將星號(*)和下劃線(_)作為強調指示符. 被一個*或者_包圍的文本將會被轉換成HTML<em>標簽的內容, 而被兩個*或者_包圍的本文則會被轉換成被HTML<strong>標簽包圍的內容. 例如輸入以下Markdown文本:
*single asterisks* _single underscores_ **double asterisks** __double underscores__
會生成
<em>single asterisks</em> <em>single underscores</em> <strong>double asterisks</strong> <strong>double underscores</strong>
你可以隨意選擇哪種風格, 唯一的限制就是強調的內容起始和結束標志必須相同.
強調符也可以用在單詞中間:
un*frigging*believable
但是如果你用空格包含一個*或者_, 那么Markdown將會把他們當做普通的星號或者下劃線.
在一些情況下星號或者下劃線可能被當做強調符號, 這時要生成一個普通的星號或者下劃線, 你可以用一個反斜杠來轉義
*this text is surrounded by literal asterisks*
代碼
可以通過重音符(`)來標記一段代碼(譯者注: 重音符在數字1鍵左邊), 與格式化的代碼段不同, 一個代碼片段用來標記一個普通段落內的代碼. 例如:
Use the 'printf()' function
將會生成:
<p>Use the <code>printf()</code> function.</p>
如果要在一個代碼行內包含一個字面常量的重音符, 你可以使用多個重音符來作為這一行的起始和開頭標記
``This is a literal backtick (`) here``
將會生成
<p><code>There is a literal backtick (`) here.</code></p>
一個代碼片段定界的重音符可以包含空格, 起始重音符之后和結束重音符之前各包含一個, 這使得你可以在代碼片段的開頭或者結尾插入字面常量的重音符.
A single backtick in a code span: `` ` `` A backtick-delimited string in a code span: `` `foo` ``
這會生成:
<p>A single backtick in a code span: <code>`</code></p> <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
使用代碼片段,&,<和>將會自動被編碼成HTML字符實體, 這樣就很容易在Markdown段落中包含HTML標簽了. Markdown會將下面的文本:
Please don't use any '<blink>' tags.
轉換成:
<p>Please don't use any <code><blink><code> tags</p>
你可以這樣寫:
`—` is the decimal-encoded equivalent of `—`.
來生成:
<p><code>&#8212;</code> is the decimal-encoded equivalent of <code>&mdash;</code>.</p>
圖片(IMAGES)
設計一種比較"自然"的語法, 能夠實現向一段純文本格式的文檔里面插入一張圖片, 是相對比較困難的一件事.
Markdown使用一種結合超鏈接的語法的方式來實現插入圖片, 并且支持兩種風格: 內聯式和引用式.
使用內聯式語法的Markdown文本是這樣的:
 
就是:
以一個感嘆號開頭: !;
緊跟一對中括號, 中括號的內容是圖片的alt屬性;
然后是一對圓括號, 包含圖片的URL和一個可選的圖片標題(title)屬性, 屬性值用單引號或者雙引號包圍起來.
引用式的圖片語法類似下面這樣:
![Alt text][id]
這里的"id" 是一個預定義的圖片引用名字. 定義圖片引用的語法與引用式鏈接定義的語法是類似的:
[id]: url/to/image "Optional title attribute"
到目前為止, Markdown還沒有制定圖片尺寸的方法; 如果有必要, 你可以直接使用HTML的<img>標簽.
...
其它(MISCELLANEOUS)
自動鏈接
Markdown為創建指向URL或者EMAIL地址的自動鏈接提供了一種快捷方式: 用一對尖括號<>把URL或者EMAIL地址包圍起來就行了. 意思就是說, 如果你想顯示URL或者EMAIL地址的值, 并且希望可以直接點擊他們(實現跳轉), 你就可以直接這樣寫:
<http://example.com/>
Markdown會把它轉換為:
<a >http://example.com/</a>
指向EMAIL地址的自動鏈接工作方式大體與鏈接相同, 不同的是, Markdown會首先對(email地址)執行一些隨機十進制和十六進制實體編碼, 以防止專門收集email地址的垃圾郵件程序. 例如, Markdown會把下面的地址:
address@example.com
轉換成:
<a href="mailto:address@example.com">address@example.com</a>
最終在HTML代碼中渲染出一個指向 "address@example.com"的鏈接.
(這種實體編碼的方法即時不能糊弄全部的地址爬蟲, 也至少可以阻止大部分, 但是肯定不會阻止掉全部的. 這樣總比什么都不做要好, 公開你的郵件地址最終會導致你收到垃圾郵件)
反斜杠轉義字符
你可以使用Markdown的反斜杠轉義字符來生成一些有特殊含義的語法的字面常量. 例如如果你想生成一個星號(*, 不是HTML中的<em>)包圍一個單詞, 你就可以在星號之前加上一個反斜杠, 像這樣:
*literal asterisks*
Markdown轉義字符可以對下面的特殊字符進行轉義:
backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
文章翻譯自Markdown創始人JOHN GRUBER的個人博客, 英文原文請參見Markdown Syntax;
本文地址:http://www.cnblogs.com/ayning/p/4393848.html
總結
以上是生活随笔為你收集整理的Markdown语法 (中文版)的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 拍摄中如何判断灰度等级_如何判断电力铁塔
- 下一篇： SPI介绍