Markdown 語法筆記

不久前狗大V —— 性感玉米 在 微博 中說：

必需要歌頌一下 Markdown 了，自稱是語法很容易 Shock 到普通 User，其實要學的，一對手就數得過來。對能熟練背誦江戶四十八手的玩家來講不是問題。簡易培訓以後（比斯大林格勒保衛戰中的肉盾培訓時間略長）炸裂到徹底能夠實如今雙手不離開鍵盤的狀況下進行簡單的格式處理（絕對夠用），偉大！相見恨晚！

哈哈哈，狗大 V 都已經在學 Markdown 了，簡直炸裂！ 不記得是去年仍是前年學習了 Markdown，相見恨晚，已經到了寫文章、文檔無 Markdown 不歡、寢食不安、沒法下指敲鍵盤的地步了。一個網站若是不支持 Markdown 在我心中更會大打折扣。學習 Markdown 已經很長時間了，Markdown 語法簡單易記，可是有時候遇到嵌套或者別的老是會有點暈。這裏記載下 Markdown 語法，以供往後查閱。

本文主要分爲如下幾部分：

• Markdown 基本語法
  
  
  • 兼容 HTML
  • 段落和換行
  • 區塊引用 Blockquotes
  • 列表
  • 代碼區塊
  • 分隔線
  • 連接
  • 強調
  • 代碼
  • 圖片
  • 自動連接
• GitHub 風格的 Markdown 語法
  
  
  • 連接自動識別
  • 圍欄式代碼塊
  • 任務清單
  • 任務清單
  • @
  • Emoji
  • table
  • 強調
• 一些和排版有關的資源
• 參考文章

Markdown 語法

想要從頭至尾一步步學習 Markdown 語法，請點擊 http://wowubuntu.com/markdown/ 閱讀, 這裏只記錄下對我來講比較容易弄混的語法。

兼容 HTML

一些 HTML 區塊元素――好比 <div>、<table>、<pre>、<p> 等標籤，必須在先後加上空行與其它內容區隔開，還要求它們的開始標籤與結尾標籤不能用製表符或空格來縮進。在 HTML 區塊標籤間的 Markdown 格式語法將不會被處理。好比，你在 HTML 區塊內使用 Markdown 樣式的 * 強調 * 會沒有效果。

這是一個普通段落。

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

這是另外一個普通段落。

效果：

這是一個普通段落。

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

這是另外一個普通段落。

段落和換行

一個 Markdown 段落是由一個或多個連續的文本行組成，它的先後要有一個以上的空行（空行的定義是顯示上看起來像是空的，便會被視爲空行。比方說，若某一行只包含空格和製表符，則該行也會被視爲空行）。普通段落不應用空格或製表符來縮進。

若是你確實想要依賴 Markdown 來插入 <br /> 標籤的話，在插入處先按入兩個以上的空格而後回車。

區塊引用

> 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 vitrisus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

效果：

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 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 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.

效果：

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

引用的區塊內也可使用其餘的 Markdown 語法，包括標題、列表、代碼區塊等：

> ## 這是一個標題。
>
> 1.   這是第一行列表項。
> 2.   這是第二行列表項。
>
> 給出一些例子代碼：
>
>     return shell_exec("echo $input | $markdown_script");

效果：

這是一個標題。

1. 這是第一行列表項。
2. 這是第二行列表項。

給出一些例子代碼：

return shell_exec("echo $input | $markdown_script");

列表

列表項目標記一般是放在最左邊，可是其實也能夠縮進，最多 3 個空格，項目標記後面則必定要接着至少一個空格或製表符。

若是列表項目間用空行分開，在輸出 HTML 時 Markdown 就會將項目內容用 <p> 標籤包起來，舉例來講：

* Bird
* Magic

會被轉換爲：

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

可是這個：

* Bird

* Magic

會被轉換爲：

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

列表項目能夠包含多個段落，每一個項目下的段落都必須縮進 4 個空格或是 1 個製表符：

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.

效果：

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.

若是要在列表項目內放進引用，那 > 就須要縮進：

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

效果：

• A list item with a blockquote:

  This is a blockquote
  inside a list item.

若是要放代碼區塊的話，該區塊就須要縮進兩次，也就是 8 個空格或是 2 個製表符：

*   一列表項包含一個列表區塊：

            <代碼寫在這>

效果：

• 一列表項包含一個列表區塊：

  <代碼寫在這>

固然，項目列表極可能會不當心產生，像是下面這樣的寫法：

1986. What a great season.

效果：

1. What a great season.

換句話說，也就是在行首出現數字-句點-空白，要避免這樣的情況，你能夠在句點前面加上反斜槓。

1986\. What a great season.

效果：

1986. What a great season.

代碼區塊

要在 Markdown 中創建代碼區塊很簡單，只要簡單地縮進 4 個空格或是 1 個製表符就能夠，一個代碼區塊會一直持續到沒有縮進的那一行（或是文件結尾）。例如，下面的輸入：

這是一個普通段落：

    這是一個代碼區塊。

效果：

這是一個普通段落：

這是一個代碼區塊。

段落和換行

你能夠在一行中用三個以上的星號、減號、底線來創建一個分隔線，行內不能有其餘東西。你也能夠在星號或是減號中間插入空格。

連接

Markdown 支持兩種形式的連接語法： 行內式 和 參考式 兩種形式。

不論是哪種，連接文字都是用 [方括號] 來標記。

要創建一個 行內式 的連接，只要在方塊括號後面緊接着圓括號並插入網址連接便可，若是你還想要加上連接的 title 文字，只要在網址後面，用雙引號把 title 文字包起來便可，例如：

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

會產生：

<p>This is <a href="http://example.com/" title="Title">
    an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
    title attribute.</p>

若是你是要連接到一樣主機的資源，你可使用相對路徑：

See my [About](/about/) page for details.

參考式 的連接是在連接文字的括號後面再接上另外一個方括號，而在第二個方括號裏面要填入用以辨識連接的標記：

This is [an example][id] reference-style link.

你也能夠選擇性地在兩個方括號中間加上一個空格：

This is [an example] [id] reference-style link.

接着，在文件的任意處，你能夠把這個標記的連接內容定義出來：

[id]: http://example.com/  "Optional Title Here"

連接內容定義的形式爲：

• 方括號（前面能夠選擇性地加上至多三個空格來縮進），裏面輸入連接文字
• 接着一個冒號
• 接着一個以上的空格或製表符
• 接着連接的網址
• 選擇性地接着 title 內容，能夠用單引號、雙引號或是括弧包着

下面這三種連接的定義都是相同：

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

請注意：有一個已知的問題是 Markdown.pl 1.0.1 會忽略單引號包起來的連接 title。

連接網址也能夠用尖括號包起來：

[id]: <http://example.com/>  "Optional Title Here"

你也能夠把 title 屬性放到下一行，也能夠加些縮進，若網址太長的話，這樣會比較好看：

[id]: http://example.com/longish/path/to/resource/here
        "Optional Title Here"

網址定義只有在產生連接的時候用到，並不會直接出如今文件之中。

連接辨別標籤能夠有字母、數字、空白和標點符號，可是並 不 區分大小寫，所以下面兩個連接是同樣的：

[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/

連接的定義能夠放在文件中的任何一個地方，我比較偏好直接放在連接出現段落的後面，你也能夠把它放在文件最後面，就像是註解同樣。

下面是一個參考式連接的範例：

I get 10 times more traffic from [Google] [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 href="http://google.com/"
    title="Google">Google</a> than from
    <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    or <a href="http://search.msn.com/" 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").

參考式的連接其實重點不在於它比較好寫，而是它比較好讀，比較一下上面的範例，使用參考式的文章自己只有 81 個字符，可是用行內形式的卻會增長到 176 個字元，若是是用純 HTML 格式來寫，會有 234 個字元，在 HTML 格式中，標籤比文本還要多。

使用 Markdown 的參考式連接，可讓文件更像是瀏覽器最後產生的結果，讓你能夠把一些標記相關的元數據移到段落文字以外，你就能夠增長連接而不讓文章的閱讀感受被打斷。

強調

Markdown 使用星號（*）和底線（_）做爲標記強調字詞的符號，被 * 或 _ 包圍的字詞會被轉成用 <em> 標籤包圍，用兩個 * 或 _ 包起來的話，則會被轉成 <strong>

可是若是你的 * 和 _ 兩邊都有空白的話，它們就只會被當成普通的符號。

若是要在文字先後直接插入普通的星號或底線，你能夠用反斜線：

代碼

若是要在代碼區段內插入反引號，你能夠用多個反引號來開啓和結束代碼區段：

``There is a literal backtick (`) here.``、

效果：

There is a literal backtick (`) here.、

圖片

Markdown 標記圖片容許兩種樣式： 行內式 和 參考式。

行內式的圖片語法看起來像是：

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

詳細敘述以下：

• 一個驚歎號 !
• 接着一個方括號，裏面放上圖片的替代文字
• 接着一個普通括號，裏面放上圖片的網址，最後還能夠用引號包住並加上
  選擇性的 'title' 文字。

參考式的圖片語法則長得像這樣：

![Alt text][id]

「id」是圖片參考的名稱，圖片參考的定義方式則和連結參考同樣：

[id]: url/to/image  "Optional title attribute"

自動連接

Markdown 支持以比較簡短的自動連接形式來處理網址和電子郵件信箱，只要是用尖括號包起來， Markdown 就會自動把它轉成連接。通常網址的連接文字就和連接地址同樣

<http://example.com/>

Markdown 會轉爲：

<a href="http://example.com/">http://example.com/</a>

電子郵件地址：

<address@example.com>

Markdown 會轉成：

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

在瀏覽器裏面，這段字串（實際上是 <a href="mailto:address@example.com"> address@example.com </a>）會變成一個能夠點擊的「address@example.com」連接。

GitHub 風格的 Markdown 語法

連接自動識別

傳統 Markdown 自動識別連接須要在連接上用一對尖括號閉合，而 GFM 只須要輸入連接即自動識別。Email 地址亦是。

圍欄式代碼塊

傳統 Markdown 使用 4 個空格縮進將文本轉換爲代碼塊，GFM 支持在代碼塊先後加三個反引號 ```，並且還能夠在代碼塊前加上語言類型標識，Github 會自動識別語言，給語法着色、代碼加亮。

例如：

```js
alet("Hello world!");
```

任務清單

列表可被轉換爲任務清單，只須要爲列表項的開頭加上 [ ] 或 [x] 便可（分別表示未完成和已完成）。

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item


- [x] 支持 @提到某人、#引用、[連接]()、**格式化** 和 <del>標籤</del> 等語法
- [x] 須要使用列表語法來激活（無序或有序列表都可）
- [x] 這是一個已完成項目
- [ ] 這是一個未完成項目

這個特性會在 Issue 和 Pull Request 的描述和評論中啓用。任務清單一樣可用於 Gist 的評論和 Markdown 格式的 Gist。在這些場合，任務清單將渲染出複選框，供勾選或清除。

@

按下 @ 符號將彈出一個列表，列出這個項目相關的人或團隊,即 @ 提到人名或團隊名時的自動補全。這個列表會隨着你的輸入不斷匹配篩選，所以一旦你在列表中發現了你要找的人名或團隊名，你就能夠用方向鍵來選中它，而後按回車或 tab 鍵來補全。對於團隊來講，只須要輸入 @組織名/團隊名，那麼團隊內的全部成員都將收到提醒。

列表的匹配範圍僅限制在當前倉庫的貢獻者以及當前討論的參與者，所以它並非一個全局性的搜索。它和文件查找器使用相同的模糊篩選算法，而且同時適用於用戶名和全名。

Emoji

按下 : 將會彈出一個表情符號的建議列表。這個列表會隨着你的輸入不斷匹配篩選，所以一旦你在列表中發現了你要找的表情符號，你就能夠按回車或 tab 鍵來補全當前高亮的那一項。

更多的 emoji 表情 能夠猛擊 EMOJI CHEAT SHEET。

table

你可使用若干列文字並於第一行下面用轉折號-分開它們，而後用管道符|隔開每一列：

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

爲了看上去美觀，你也能夠在兩端加上額外的管道符：

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

注意頂部的虛線不須要準確匹配表頭文本的長度：

| Name | Description          |
| ------------- | ----------- |
| Help      | Display the help window.|
| Close     | Closes a window     |

你也能夠在其中包括內聯 Markdown 元素，好比連接，加粗，斜體或刪除

| Name | Description          |
| ------------- | ----------- |
| Help      | ~~Display the~~ help window.|
| Close     | _Closes_ a window     |

最後，經過在表頭行加入冒號:，你能夠決定文本是左對齊，右對齊，仍是居中：

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |

一個在最左邊的冒號表示一個左對齊的列；一個在最右邊的冒號表示一個右對齊的列；兩邊都有的冒號表示一個居中的列。

強調

用在字母中間放一條線來強調文字 可以使用

~~this~~

效果爲

this

一些和排版有關的資源

• Web 中文字體應用指南
• 中文排版的最佳實踐

• Entry.css

  Customizable and readable less library for Chinese text. 一個可配置的、更適合閱讀的中文文章樣式庫

• typo.css

  中文網頁重設與排版：一致化瀏覽器排版效果，構建最適合中文閱讀的網頁排版

• yue.css

  A typography stylesheet for readable content

• chinese-copywriting-guidelines

  Chinese Copywriting Guidelines：中文文案排版指北

• Han.css

  「漢字標準格式」印刷品般的漢字排版框架 Han.css: the CSS typography framework optimised for Hanzi.

參考文章

• http://wowubuntu.com/markdown/
• https://github.com/cssmagic/blog/issues/13
• https://help.github.com/articles/github-flavored-markdown/
• https://guides.github.com/features/mastering-markdown/
• https://guides.github.com/features/mastering-markdown/

本文同步更新於個人博客 paddingme,文章連接爲：http://padding.me/blog/2015/01/14/my-markdown-syntax-notes/