`、``、`
This is another regular paragraph.
請注意,Markdown 語法在 HTML 區塊標籤中將不會被進行處理。例如,你無法在 HTML 區塊內使用 Markdown 形式的`*強調*`。
HTML 的區段標籤如 ``、``、`` 則不受限制,可以在 Markdown 的段落、清單或是標題裡任意使用。依照個人習慣,甚至可以不用Markdown 格式,而採用 HTML 標籤來格式化。舉例說明:如果比較喜歡 HTML 的 `` 或 `` 標籤,可以直接使用這些標籤,而不用 Markdown 提供的連結或是影像標示語法。
HTML 區段標籤和區塊標籤不同,在區段標籤的範圍內, Markdown 的語法是有效的。
### 特殊字元自動轉換
在 HTML 文件中,有兩個字元需要特殊處理: `<` 和 `&` 。 `<` 符號用於起始標籤,`&` 符號則用於標記 HTML 實體,如果你只是想要使用這些符號,你必須要使用實體的形式,像是 `<` 和 `&`。
`&` 符號其實很容易讓寫作網路文件的人感到困擾,如果你要打「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 將不會對這段文字做修改,但是如果你這樣寫:
AT&T
Markdown 就會將它轉為:
AT&T
類似的狀況也會發生在 `<` 符號上,因為 Markdown 支援 [行內 HTML](#html) ,如果你是使用 `<` 符號作為 HTML 標籤使用,那 Markdown 也不會對它做任何轉換,但是如果你是寫:
4 < 5
Markdown 將會把它轉換為:
4 < 5
不過需要注意的是,code 範圍內,不論是行內還是區塊, `<` 和 `&` 兩個符號都*一定*會被轉換成 HTML 實體,這項特性讓你可以很容易地用 Markdown 寫 HTML code (和 HTML 相對而言, HTML 語法中,你要把所有的 `<` 和 `&` 都轉換為 HTML 實體,才能在 HTML 文件裡面寫出 HTML code。)
* * *
## 區塊元素
### 段落和換行
一個段落是由一個以上相連接的行句組成,而一個以上的空行則會切分出不同的段落(空行的定義是顯示上看起來像是空行,便會被視為空行。比方說,若某一行只包含空白和 tab,則該行也會被視為空行),一般的段落不需要用空白或斷行縮排。
「一個以上相連接的行句組成」這句話其實暗示了 Markdown 允許段落內的強迫斷行,這個特性和其他大部分的 text-to-HTML 格式不一樣(包括 MovableType 的「Convert Line Breaks」選項),其它的格式會把每個斷行都轉成 `
` 標籤。 如果你*真的*想要插入 `
` 標籤的話,在行尾加上兩個以上的空白,然後按 enter。 是的,這確實需要花比較多功夫來插入 `
` ,但是「每個換行都轉換為 `
`」的方法在 Markdown 中並不適合, Markdown 中 email 式的 [區塊引言][bq] 和多段落的 [清單][l] 在使用換行來排版的時候,不但更好用,還更好閱讀。 [bq]: #blockquote [l]: #list ### 標題 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 樣式的標題,這純粹只是美觀用的,若是覺得這樣看起來比較舒適,你就可以在行尾加上 `#`,而行尾的 `#` 數量也不用和開頭一樣(行首的井字數量決定標題的階數): # This is an H1 # ## This is an H2 ## ### This is an H3 ###### ### Blockquotes 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 很重要的一點是,你在清單標記上使用的數字並不會影響輸出的 HTML 結果,上面的清單所產生的 HTML 標記為:
`、`` 等標籤,必須在前後加上空行,以利與內容區隔。而且這些(元素)的開始與結尾標籤,不可以用 tab 或是空白來縮排。Markdown 的產生器有智慧型判斷,可以避免在區塊標籤前後加上沒有必要的 `
` 標籤。 舉例來說,在 Markdown 文件裡加上一段 HTML 表格: This is a regular paragraph.
Foo |
` 標籤。 如果你*真的*想要插入 `
` 標籤的話,在行尾加上兩個以上的空白,然後按 enter。 是的,這確實需要花比較多功夫來插入 `
` ,但是「每個換行都轉換為 `
`」的方法在 Markdown 中並不適合, Markdown 中 email 式的 [區塊引言][bq] 和多段落的 [清單][l] 在使用換行來排版的時候,不但更好用,還更好閱讀。 [bq]: #blockquote [l]: #list ### 標題 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 樣式的標題,這純粹只是美觀用的,若是覺得這樣看起來比較舒適,你就可以在行尾加上 `#`,而行尾的 `#` 數量也不用和開頭一樣(行首的井字數量決定標題的階數): # This is an H1 # ## This is an H2 ## ### This is an H3 ###### ### Blockquotes 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 很重要的一點是,你在清單標記上使用的數字並不會影響輸出的 HTML 結果,上面的清單所產生的 HTML 標記為:
- Bird
- McHale
- Parish
` 標籤包起來,舉例來說: * Bird * Magic 會被轉換為:
- Bird
- Magic
Bird
Magic
當然,項目清單很可能會不小心產生,像是下面這樣的寫法:
1986. What a great season.
換句話說,也就是在行首出現*數字-句點-空白*,要避免這樣的狀況,你可以在句點前面加上反斜線。
1986\. What a great season.
### 程式碼區塊
和程式相關的寫作或是標籤語言原始碼通常會有已經排版好的程式碼區塊,通常這些區塊我們並不希望它以一般段落文件的方式去排版,而是照原來的樣子顯示,Markdown 會用 `` 和 `` 標籤來把程式碼區塊包起來。
要在 Markdown 中建立程式碼區塊很簡單,只要簡單地縮排 4 個空白或是 1 個 tab 就可以,例如,下面的輸入:
This is a normal paragraph:
This is a code block.
Markdown 會轉換成:
This is a normal paragraph:
This is a code block.
這個每行一階的縮排(4 個空白或是 1 個 tab),都會被移除,例如:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
會被轉換為:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
一個程式碼區塊會一直持續到沒有縮排的那一行(或是文件結尾)。
在程式碼區塊裡面, `&` 、 `<` 和 `>` 會自動轉成 HTML 實體,這樣的方式讓你非常容易使用 Markdown 插入範例用的 HTML 原始碼,只需要複製貼上,再加上縮排就可以了,剩下的 Markdown 都會幫你處理,例如:
會被轉換為:
<div class="footer">
© 2004 Foo Corporation
</div>
程式碼區塊中,一般的 Markdown 語法不會被轉換,像是星號便只是星號,這表示你可以很容易地以 Markdown 語法撰寫 Markdown 語法相關的文件。
### 分隔線
你可以在一行中用三個或以上的星號、減號、底線來建立一個分隔線,行內不能有其他東西。你也可以在星號中間插入空白。下面每種寫法都可以建立分隔線:
* * *
***
*****
- - -
---------------------------------------
* * *
## 區段元素
### 連結
Markdown 支援兩種形式的連結語法: *行內*和*參考*兩種形式。
不管是哪一種,連結的文字都是用 [方括號] 來標記。
要建立一個行內形式的連結,只要在方塊括號後面馬上接著括號並插入網址連結即可,如果你還想要加上連結的 title 文字,只要在網址後面,用雙引號把 title 文字包起來即可,例如:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
會產生:
This is
an example inline link.
This link has no
title attribute.
如果你是要連結到同樣主機的資源,你可以使用相對路徑:
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"
連結定義的形式為:
* 方括號,裡面輸入連結的辨識用標籤
* 接著一個冒號
* 接著一個以上的空白或 tab
* 接著連結的網址
* 選擇性地接著 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]: "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。
I get 10 times more traffic from Google than from
Yahoo
or MSN.
下面是用行內形式寫的同樣一段內容的 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 使用星號(`*`)和底線(`_`)作為標記強調字詞的符號,被 `*` 或 `_` 包圍的字詞會被轉成用 `` 標籤包圍,用兩個 `*` 或 `_` 包起來的話,則會被轉成 ``,例如:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
會轉成:
single asterisks
single underscores
double asterisks
double underscores
你可以隨便用你喜歡的樣式,唯一的限制是,你用什麼符號開啟標籤,就要用什麼符號結束。
強調也可以直接插在文字中間:
un*frigging*believable
但是如果你的 `*` 和 `_` 兩邊都有空白的話,它們就只會被當成普通的符號。
如果要在文字前後直接插入普通的星號或底線,你可以用反斜線:
\*this text is surrounded by literal asterisks\*
### 程式碼
如果要標記一小段行內程式碼,你可以用反引號把它包起來(`` ` ``),例如:
Use the `printf()` function.
會產生:
Use the printf()
function.
如果要在程式碼區段內插入反引號,你可以用多個反引號來開啟和結束程式碼區段:
``There is a literal backtick (`) here.``
這段語法會產生:
There is a literal backtick (`) here.
程式碼區段的起始和結束端都可以放入一個空白,起始端後面一個,結束端前面一個,這樣你就可以在區段的一開始就插入反引號:
A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
會產生:
A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`
在程式碼區段內,`&` 和方括號都會被轉成 HTML 實體,這樣會比較容易插入 HTML 原始碼,Markdown 會把下面這段:
Please don't use any `
- Markdown Syntaxdescription canonical markdown syntax markdown syntax syntax abstract_syntax_tree error incompatible version syntax sqlsyntaxerrorexception caused syntax问题 39 syntax sqlsyntaxerrorexception your syntax your corresponds the syntax sqlsyntaxerrorexception your corresponds unexpected config syntax flink