關(guān)于簡(jiǎn)書(shū) Markdown

Markdown 語(yǔ)法的目標(biāo): 成為一種適用于網(wǎng)絡(luò)的書(shū)寫(xiě)語(yǔ)言。
本文的目的：使讀者輕松了解簡(jiǎn)書(shū)對(duì) Markdown 語(yǔ)法的支持，了解其優(yōu)點(diǎn)和不足。能夠在選擇時(shí)正確取舍，使用時(shí)得心應(yīng)手。

一、區(qū)塊標(biāo)記

區(qū)塊標(biāo)記：是指內(nèi)容獨(dú)占一塊，需前后換行，不和其他標(biāo)記共處一行的標(biāo)記。

1. 段落

段落：即是一段連續(xù)的文字，可包含*、空格、換行、tab等字符。兩個(gè)段落之間使用空行分隔。

示例代碼

效果

第一自然段

第二自然段

注意：換行不是分段的標(biāo)識(shí)，空行才是

2. 標(biāo)題

標(biāo)題：代表了文章中主題的層次，比如：文章標(biāo)題使用一級(jí)標(biāo)題，回目名稱使用二級(jí)標(biāo)題，小節(jié)使用三級(jí)標(biāo)題，依次類推。主題的層次代表了文章的大綱。

語(yǔ)法：Markdown 中使用連續(xù)的 n(1-6) 個(gè) # 分別表示第 n 級(jí)標(biāo)題。
示例代碼

效果

一級(jí)標(biāo)題

二級(jí)標(biāo)題

三級(jí)標(biāo)題

四級(jí)標(biāo)題

五級(jí)標(biāo)題

六級(jí)標(biāo)題

注：# 和后續(xù)內(nèi)容之間應(yīng)放置一個(gè)空格

3. 列表

列表：就是一組相關(guān)信息的集合。簡(jiǎn)書(shū)中的列表分為 有序列表 和 無(wú)序列表。

1) 有序列表

語(yǔ)法：使用 數(shù)字 + . 作為項(xiàng)目符號(hào)，項(xiàng)目符號(hào)和正式列表項(xiàng)目之間有一個(gè)空格。

示例代碼

效果

1. 打開(kāi)冰箱門
2. 把大象放進(jìn)冰箱
3. 關(guān)上冰箱門

2) 無(wú)序列表

語(yǔ)法：使用 * 作為項(xiàng)目符號(hào)，項(xiàng)目符號(hào)和正式列表項(xiàng)目之間有一個(gè)空格。

示例代碼

效果

• 吃飯
• 睡覺(jué)
• 打豆豆

注意事項(xiàng)：

• 無(wú)序列表的項(xiàng)目符號(hào)可使用 *,+,- 效果是相同的。
• 列表與后續(xù)內(nèi)容之間需要一個(gè)空行隔開(kāi)，即：列表是一個(gè)段落
• 列表允許多層次嵌套
• 可以在項(xiàng)目中包含段落，只需將段落前添加一個(gè) tab 或 4 個(gè)空格

4. 分割線

語(yǔ)法：使用 3 個(gè)連續(xù)的 * 即可得到一個(gè)分割線

示例代碼

效果

5. 引用

語(yǔ)法：在行頭加上 > 即可。

這里是一段引用

注意事項(xiàng)：

• 大于號(hào) 和 文字必須有一個(gè)空格
• 可以在每行之前加 > ，也可以在段落之前加 1 個(gè) >
• 引用內(nèi)部可以使用其他 Markdown 標(biāo)記

  引用內(nèi)部可以添加新的引用，只需再加一個(gè)大于號(hào)

二、行內(nèi)標(biāo)記

行內(nèi)標(biāo)記和其他標(biāo)記共處一行。

1. 強(qiáng)調(diào)文字

1) 斜體

語(yǔ)法：使用前后各 1 個(gè) *(或_) 包含的文字是 斜體 文字
示例代碼

效果

斜體, 斜體

2) 粗體

語(yǔ)法：使用前后各 2 個(gè) *(或_) 包含的文字是 粗體 文字
示例代碼

效果

粗體，__粗體__

3) 刪除文字

語(yǔ)法：使用前后各 2 個(gè) ~ 包含的文字是刪除文字
示例代碼

效果

刪除

4) 粗斜體

語(yǔ)法：在**(或__)中嵌套_ (或*) 或 在_(或*)中嵌套**(或__)即可得到 粗斜體。

示例代碼

效果

粗斜體， 粗斜體
粗斜體， 粗斜體

2. 圖片與鏈接

1) 圖片：行內(nèi)圖片、引用圖片

1> 行內(nèi)圖片
圖片和圖片地址寫(xiě)在一起。
語(yǔ)法： ![圖片標(biāo)題](圖片url)
示例代碼

效果

史努比

注意事項(xiàng)

在簡(jiǎn)書(shū)中，圖片可以直接拖到編輯區(qū)，會(huì)自動(dòng)上傳圖片并生成圖片地址。本功能是簡(jiǎn)書(shū)提供的一大便利，值得表?yè)P(yáng)！

2> 引用圖片
圖片和圖片地址分開(kāi)書(shū)寫(xiě)。
語(yǔ)法：
![圖片標(biāo)題][圖片id]
[圖片id]:圖片url

示例代碼：

效果

史努比

注意事項(xiàng)

引用圖片的 id 在文章中必須唯一

2) 鏈接：行內(nèi)鏈接、鏈接引用、自動(dòng)鏈接

1> 行內(nèi)鏈接
語(yǔ)法：[鏈接名稱](鏈接地址 url '鏈接title')
示例代碼

效果

新浪

注意事項(xiàng)

雙引號(hào)中的內(nèi)容是鏈接的 title (目前漢字顯示不正確)

2> 鏈接引用
一種鏈接和地址分離的方式。
語(yǔ)法：
[鏈接名稱][鏈接id]
[鏈接id]:鏈接 url 地址 '鏈接 title'

示例代碼

效果
根據(jù) 雅虎 的調(diào)查，希拉里將當(dāng)選；根據(jù) 谷歌 的調(diào)查，川普將當(dāng)選。

注意事項(xiàng)

鏈接 id 可使用字母、數(shù)字、空格，但不區(qū)分大小寫(xiě)

3> 自動(dòng)鏈接
一種簡(jiǎn)明的鏈接書(shū)寫(xiě)方式
語(yǔ)法：<鏈接地址>

示例代碼

效果

http://www.sina.com.cn

3. 腳注

為名詞提供注釋，注釋將顯示在文章末尾。
語(yǔ)法：
待解釋文字[^腳注 id]
[^腳注 id]:注釋內(nèi)容

示例代碼

效果
Hello程序^[1]

• 腳注 id 必須唯一
• 無(wú)論腳注 id 如何起名，顯示時(shí)一律標(biāo)為數(shù)字，并且按出現(xiàn)順序排列

三、雙標(biāo)記

既可作為區(qū)塊標(biāo)記又可作為行內(nèi)標(biāo)記的標(biāo)記。

1. 代碼塊

1) 行內(nèi)代碼塊

語(yǔ)法：使用兩個(gè) ` 將代碼包含起來(lái)

示例代碼

效果

在 Java 輸出 Hello, world ：System.out.print('Hello, World!');

2) 多行代碼塊

語(yǔ)法：只需要每行都縮進(jìn) 4 個(gè)空格即可，或者使用```框起來(lái)。

示例代碼 1 (行前4個(gè)空格)

// JQuery 的 Hello, world
$(function(){
alert('Hello, world!')
});

效果(行前4個(gè)空格)

示例代碼 2 (```)

```
// JQuery 的 Hello, world
$(function(){
alert('Hello, world!')
});
```

效果 (```)

注意事項(xiàng)：

1. 在代碼區(qū)塊內(nèi)部，', <>,& 將會(huì)自動(dòng)轉(zhuǎn)換為轉(zhuǎn)義字符
2. 在代碼區(qū)塊內(nèi)部，Markdown 標(biāo)記將保持原樣，即：星號(hào)(*)就是星號(hào)(*)，不被解釋為特殊標(biāo)記，這樣就可以不能繼續(xù)使用 Markdown 語(yǔ)法了

四、表格

語(yǔ)法：

1. 第一行為表頭，第二行分隔表頭和主體部分，第三行開(kāi)始每一行為一個(gè)表格行。
2. 列于列之間用管道符 | 隔開(kāi)。表格每一行兩邊的管道符可省略。
3. 第二行還可以為不同的列指定對(duì)齊方向。標(biāo)題默認(rèn)為居中對(duì)齊，內(nèi)容默認(rèn)為左對(duì)齊；在 - 左邊加上 : 就是左對(duì)齊；在 - 右邊加上 : 就是右對(duì)齊；在 - 兩邊都加上 : 就是居中對(duì)齊。

示例代碼

效果

五、其他問(wèn)題

1. Markdown 與 HTML 的關(guān)系

1. HTML 是一種發(fā)布的格式，Markdown 是一種書(shū)寫(xiě)的格式。
2. Markdown 的格式語(yǔ)法只涵蓋純文本可以涵蓋的范圍。
3. 在 Markdown 中可直接使用 HTML 標(biāo)簽，但需要注意

   • 對(duì)于 HTML 區(qū)塊元素――如 div、table、pre、p 等標(biāo)簽，必須在前后加上空行與其它內(nèi)容區(qū)隔開(kāi)，還要求它們的開(kāi)始標(biāo)簽與結(jié)尾標(biāo)簽不能用制表符(tab)或空格來(lái)縮進(jìn)
   • HTML 的行內(nèi)標(biāo)簽——如 span、cite、del 可以在 Markdown 的段落、列表或是標(biāo)題里隨意使用。
   • 在 HTML 的區(qū)塊標(biāo)簽中的 Markdown 標(biāo)簽是沒(méi)有效果的

2. 特殊字符的自動(dòng)轉(zhuǎn)換

• 在 HTML 文件中，有兩個(gè)字符需要特殊處理： < 和="" &，必須使用轉(zhuǎn)義字符：&="" lt="" ;="" 和="" &="" amp="">
• Markdown 中，你可以自由的書(shū)寫(xiě) < 和="" &，編輯器會(huì)智能的進(jìn)行判斷：當(dāng)這些符號(hào)用于="" html="">
• 在代碼塊中，它們將統(tǒng)統(tǒng)被轉(zhuǎn)換為字符實(shí)體，即：原樣顯示。

3. Markdown 中的轉(zhuǎn)義字符

Markdown 中，如需顯示有特定意義的符號(hào)，如：*,# 等，可使用 反斜杠 \ 進(jìn)行轉(zhuǎn)義?？蓪?duì)如下字符進(jìn)行轉(zhuǎn)義：

六、簡(jiǎn)書(shū)尚不支持的標(biāo)記和不足

1. 用于生成目錄索引的 [TOC]
2. 用于說(shuō)明文章標(biāo)簽的 tags
3. 定義列表和待辦事宜 Todo 列表
4. 數(shù)學(xué)公式
5. 各種圖形：流程圖、時(shí)序圖、甘特圖
6. 其他技術(shù)，如：{mermaid}
7. 區(qū)塊代碼中不顯示行號(hào)

七、給簡(jiǎn)書(shū)的一點(diǎn)建議

1. 對(duì)于普通用戶來(lái)講，定義列表、生成目錄索引和文章標(biāo)簽功能是十分必要的，希望能夠盡快增加這些功能。希望能夠?qū)崿F(xiàn)預(yù)覽圖和編輯器的同步滾動(dòng)功能。
2. 對(duì)于理工狗來(lái)講，編輯 LaTex 數(shù)學(xué)公式是非常必要的功能，希望能夠盡快增加這個(gè)功能。
3. 對(duì)于代碼狗來(lái)講，區(qū)塊代碼中顯示行號(hào)，以及流程圖、時(shí)序圖是非常必要的功能，希望能夠盡快增加這些功能。
4. 其他的諸如：待辦事宜列表、甘特圖，mermaid等功能，可以慢慢實(shí)現(xiàn)。

跋

由于本人初來(lái)乍到，水平有限，難免有疏漏錯(cuò)誤，萬(wàn)望指教，不勝感激。

[1]:即：Hello, world 程序 ?