概述
宗旨
<p>Markdown 的目標是實現【易讀易寫】。</p>
<p>可讀性,無論如何都是最重要的。一份使用Markdown 格式撰寫的文件應該可以直接以純文本發布,并且看起來不會是由很多標簽或是格式命令組成。Markdown 語法受到一些既有 text-HTML 格式的影響,而最大靈感其實是純文本電子郵件格式的影響。</p>
總之,Markdown 的語法全由一些符號組成,這些符號經過精挑細選,其作用一目了然。比如:在文字兩旁加上星號(*),看起來就是強調。Markdown 的列表看起來,嗯,就是列表。Markdown 的區塊引用看起來就像是引用一段文字。
兼容HTML
<p>Markdown 語法的目標是:成為一種適用于網絡的<em>書寫</em>語音。</p>
<p>Markdown 不是要取代 HTML,甚至也不是要和它接近。它的語法種類很少,只占 HTML 標記的一小部分。Markdown 的構想<em>不是</em>要使得 HTML 更易書寫。Markdown的理念是,能讓文檔更容易讀、寫和隨意改。HTML 是一種<em>發布</em>的格式,Markdown 是一種<em>書寫</em>的格式。就這樣,Markdown 的格式語法只覆蓋純文本可以涵蓋的范圍。</p>
<p>不在 Markdown 涵蓋范圍之內的標簽,都可以直接在文檔里面用 HTML 撰寫。不需要額外標注這是 HTML 或是 Markdown ;只要直接加標簽就可以了。</p>
<p>要制約的只有一些 HTML 區塊元素—比如 '<div>'、 <code><table></code> 等標簽,必須要在前后加上空行與其他內容區隔開,還要求它們的開始標簽與結尾標簽不能用制表符或空格來縮進。</p>
<p>例子如下,在 Markdown 文件里加上一段 HTML 表格:</p>
<pre><code>這是一個普通段落。
<table>
<tr>
<td>Foo</td>
</tr>
</table>
這是另一個普通段落。
</code></pre>
<p>請注意,在 HTML 區塊標簽間的 Markdown 格式語法將不會被處理。比如,你在 HTML 區塊內使用 Markdown 樣式的強調會沒有效果。</p>
HTML 的區段(行內)標簽如<code><span></code>、<code><del></code> 可以在Markdown 的段落、列表或是標題里隨意使用。依照個人習慣,甚至直接可以用 HTML 標簽來格式化。舉例說明,如果比較喜歡 HTML 的<code><<img>></code>標簽,可以直接使用這些標簽,而不用 Markdown 提高的鏈接或是圖像標簽語法。</p>
<p>和處在 HTML 區塊標簽間不同,Markdown 語法在 HTML 區段標簽間是有效的。</p>
特殊字符自動轉換
在 HTML 文件中,有兩個字符需要特別處理:<code><</code>、<code>&</code> 。<code><</code> 用于起始標簽,<code>&</code> 用于標記 HTML 實體。如果你只是要使用這個符號,你必須要使用實體的形式,比如,像是 < 、& 。
<code>&</code> 字符尤其讓網絡文檔編寫者受折磨,如果你要打 AT&T, 你必須要寫成 ‘AT&T’ 。而網址中的 & 也要轉換。如果要鏈接到:
http://images.google.com/images?num=30&q=larry+bird
你必須把網址轉換寫為
http://images.google.com/images?num=30&q=larry+bird
才能放到鏈接標簽的 href 屬性里。不用說也知道這很容易忽略。這也可能是 HTML 標準檢驗所檢查到的錯誤中,數量最多的。
Markdown 讓你可以自然地書寫字符,需要轉換的由它來處理就好了。如果你使用的 & 字符是 HTML 字符實體的一部分,它會保留原狀,否則它會轉換成 &
。
所以,如果要在文檔中插入一個版權符號?,你可以這樣寫:
?
Markdown 會保留它不動。
需要注意的是, code 范圍內,不論是行內還是區塊, <
和 &
兩個符號都一定會被轉換成 HTML 實體,這項特性讓你可以用 Markdown 寫 HTML code 。
區塊元素
段落和換行
<p>一個 Markdown 段落是由一個或多個連續的文本行組成,它的前后要有一個以上的空行(空行的定義是顯示上看起來像是空的,便會被視為空行。比如,若某一行只含空格和 Tab, 則該行業將視為空行)。普通段落不該用空格或 Tab 來縮進。</p>
「一個以上相連接的行句組成」這句話其實暗示了 Markdown 允許段落內的強迫斷行,這個特性和其他大部分的 text-to-HTML 格式不一樣(包括 MovableType 的「Convert Line Breaks」選項),其它的格式會把每個斷行都轉成 <br />
標簽。
標題
區塊引用
Markdown 標記區塊引用是使用類似 email 中用 >
的引用方式。
This is a blockquote with two paragraphs.
Markdown也允許你偷懶只在整個段落的第一行最前面加上>
:
區塊引用可以嵌套,只要根據層次加上不同數量的 >
:
This is the first level of quoting.
This is nested blackquote.
Back to the first level.
引用的區塊內也可以使用其他的 Markdown 語法,包括標題、列表、代碼區塊等:
This is a header.
This is the first list item.
This is the second list item.
Here's some example code:
return shell_exec("echo $input | $markdown_script");
清單
Markdown 支持有序清單和無序清單。
無序清單使用星號、加號或減號作為清單標記。
* red
* green
* purple
等同于:
- red
- green
- purple
也等同于
- red
- green
- purple
有序清單則使用數字接著一個英文句點:
- bird
- McHale
- Parish
要讓清單看起來更漂亮,你可以把內容用固定的縮排整理好:
《 Fantastic animals 》is an impressive movie i have watched in this year.
《神奇動物在哪里》這部電影讓我印象深刻,里面的 魔法生物各有各的特點。
如果清單項目用空行隔開,Markdown 會把項目內容在輸出時用<p>
標簽包起來,舉例來說:
Bird
Magic
會被轉換為:
<ul>
<li>Bird</li>
<li><p>Magic</p></li>
</ul>
項目清單很有可能會不小心產生,如:
1986.
It is a great season.
換句話說,在行首出現 數字-句號-空白 ,要避免這樣的情況,可以在數字后加斜線:
1986/. It is a great season.
程序區塊
和程序相關的寫作或者標記語言原始代碼通常會有已經排版好的程序區塊,通常這些區塊我們并不希望它以一般段落文件的形式去排版,而是原來的樣子。Markdown 會用<pre>
和<code>
把程序區塊包起來。
要在 Markdown 中建立程序區塊很簡單,只要縮排4個空白或是1個tab即可。
分隔線
用三個以上的星號、減號、底線來建立一個分隔線,行內不能有其他東西。
-----
區內要素
鏈接
Markdown 支持行內和參考兩種形式的鏈接語法。不管是哪一種,鏈接的文字都是用[方括號]來標記。
要建立一個行內形式的鏈接,只需要在方括號的后面馬上接著括號并插入網頁鏈接即可,如果你還想要加上鏈接的 title 文字,只要在網址后面,用雙引號把 title 文字包起來即可。
參與形式的鏈接使用另外一個方括號接在鏈接文字的括號后面,而在第二個方括號后面要填入用以辨別鏈接的標簽。接著,在文章的任意處,你可以把這個標簽的鏈接內容定義出來。
鏈接定義的形式為:
- 方括號,里面輸入鏈接的辨識用標簽
- 接著一個冒號
- 接著一個以上的空白或tab
- 接著鏈接的網址
- 選擇性地接著title內容,可以用單引號、雙引號或者括弧包著
你也可以把title屬性放到下一行,也可以加一些縮排,網址太長的話,這樣比較美觀。
舉例:
I get 10 traffics from Google than from [Yahoo] [2] or [MSN] [3].
1: http://google.com "Google"
[2]: http://search.yahoo.com "Yahoo"
[3]: http://search.msn.com "MSN"
強調
Markdown 使用星號()和底線(_)作為標記強調字詞的符號,被 * 或 _ 包圍的字詞會被轉換成用<em>標簽包圍,用兩個 或 _ 包圍的字詞會被轉換成<strong>.
但是如果*
、_
兩邊都有空白的話,他們就只會看被當做普通的符號。
如果要在文字前后直接插入普通的星號或底線,可以用反斜線:
\這段文字沒有被強調\
圖片
圖片與鏈接的插入方法相似,只是在鏈接的語法前加上了!
。
注:本文內容引用自 Markdown語法說明繁體版, 練習Markdown語法所用。