【經(jīng)驗(yàn)分享】如何使用Markdown編寫技術(shù)文檔？

1 概述

Markdown是一種輕量級(jí)標(biāo)記語(yǔ)言，創(chuàng)始人為約翰·格魯伯（英語(yǔ)：John Gruber）。 它允許人們使用易讀易寫的純文本格式編寫文檔，然后轉(zhuǎn)換成有效的XHTML（或者HTML）文檔。這種語(yǔ)言吸收了很多在電子郵件中已有的純文本標(biāo)記的特性。

由于Markdown的輕量化、易讀易寫特性，并且對(duì)于圖片，圖表、數(shù)學(xué)式都有支持，許多網(wǎng)站都廣泛使用Markdown來(lái)撰寫幫助文檔或是用于論壇上發(fā)表消息。 如GitHub、Reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge、簡(jiǎn)書等，甚至還能被使用來(lái)撰寫電子書。

2 幾種支持Markdown語(yǔ)法的工具、軟件介紹

2.1 Typroa

Typroa 是我常用的編輯器，熟悉了Markdown語(yǔ)法了，你會(huì)用起來(lái)非常順手。它的設(shè)計(jì)與別人編輯器最大的區(qū)別是，它支持 “所見(jiàn)即所得”，一邊編寫，立馬就預(yù)覽，效率高，也很流暢。

特色功能：可以支持外部圖床設(shè)置，直接把截圖貼上來(lái)，立馬可以上傳到圖床，生成訪問(wèn)鏈接，這個(gè)功能非常暫。

2.2 sublime插件

可以參考這個(gè) 鏈接 嘗試安裝看看，不過(guò)我試了，效果并不理想。

2.3 Cmd Markdown

這個(gè)有點(diǎn)特別，它既支持 在線網(wǎng)頁(yè)編輯器，也支持本地化的編輯器。采用的是左編輯、右預(yù)覽的設(shè)計(jì)。新手可以考慮使用下。

2.4 在線云筆記之類的平臺(tái)

有道云筆記：使用了，不太符合我的習(xí)慣；不過(guò)作為在線筆記倒是可以考慮。

語(yǔ)雀筆記：沒(méi)使用過(guò)，感興趣可以嘗試下。

印象筆記: 沒(méi)有使用過(guò)，感興趣可以嘗試下。

還有其他。。。

2.5 技術(shù)博客平臺(tái)的編輯器

常見(jiàn)的技術(shù)博客平臺(tái)，比如CSDN、簡(jiǎn)書、博客園、oschina.net等都支持Markdown版本的編輯器。

2.6 總結(jié)

蘿卜青菜，各有所愛(ài)！選擇一款適合自己的，多使用，孰能生巧！

3 常用語(yǔ)法

3.1 目錄相關(guān)

1 這是1級(jí)目錄

1.1 這是2級(jí)目錄

1.1.1 這是3級(jí)目錄

1.1.1.1 這是4級(jí)目錄

1.1.1.1.1 這是5級(jí)目錄

1.1.1.1.1.1 這是6級(jí)目錄

注意，一般最大支持 6 級(jí)目錄，這樣滿足我們的日常寫作需求了。

3.2 文本相關(guān)

這個(gè)是加粗！ 這個(gè)是斜體！ 這個(gè)是斜體加粗！ ~~這個(gè)是字體刪除！~~這個(gè)是文字加底色 (實(shí)則是代碼的寫法，下面會(huì)講)

3.3 列表相關(guān)

gg

gg

gg

ggg

gg

ggg

fff

有序列表4（加粗）

有序列表3

有序列表2

有序列表1 a. 有序列表 b. 有序列表

（數(shù)字 加 . 加 空格；支持多級(jí)嵌套）

無(wú)序列表

無(wú)序列表

哈哈哈

無(wú)序列表

無(wú)序列表

（-或*或+ 加 空格；支持多級(jí)嵌套）

3.4 代碼相關(guān)

這是單行代碼：printf("hello world!\r\n");

int main(void)

{

printf("hello world!\r\n");

return 0;

}

3.5 圖片相關(guān)

語(yǔ)法規(guī)則:

3.6 超鏈接相關(guān)

這里是百度的超鏈接描述

語(yǔ)法規(guī)則: 描述

3.7 文字引用

這是一段引用文字

引用可以嵌套

引用可以嵌套 這是一段引用文字

3.8 水平分隔線

【三個(gè)橫桿或三個(gè)星號(hào)或三個(gè)下劃線，+ 回車】

3.9 表格相關(guān)

4 高階功能

4.1 to-do-list

[x] done-list-3

[x] done-list-2

[x] done-list-1

[ ] to-do-list-3

[ ] to-do-list-2

[ ] to-do-list-1

4.2 流程圖

st=>start: Start

op=>operation: Your Operation

cond=>condition: Yes or No?

e=>end

st->op->cond

cond(yes)->e

cond(no)->op

st=>start: 開始框

op=>operation: 處理框

cond=>condition: 判斷框(是或否?)

sub1=>subroutine: 子流程

io=>inputoutput: 輸入輸出框

e=>end: 結(jié)束框

st(right)->op(right)->cond

cond(yes)->io(bottom)->e

cond(no)->sub1(right)->op

st=>start: 開始框

op=>operation: 處理框

cond=>condition: 判斷框(是或否?)

sub1=>subroutine: 子流程

io=>inputoutput: 輸入輸出框

e=>end: 結(jié)束框

st->op->cond

cond(yes)->io->e

cond(no)->sub1(right)->op

4.3 時(shí)序圖

Alice->Bob: Hello Bob, how are you?

Note right of Bob: Bob thinks

Bob-->Alice: I am good thanks!

【注意：這個(gè)不是每個(gè)Markdown編輯器都支持的渲染功能】

Title: 標(biāo)題：復(fù)雜使用

對(duì)象A->對(duì)象B: 對(duì)象B你好嗎?（請(qǐng)求）

Note right of 對(duì)象B: 對(duì)象B的描述

Note left of 對(duì)象A: 對(duì)象A的描述(提示)

對(duì)象B-->對(duì)象A: 我很好(響應(yīng))

對(duì)象B->小三: 你好嗎

小三-->>對(duì)象A: 對(duì)象B找我了

對(duì)象A->對(duì)象B: 你真的好嗎？

Note over 小三,對(duì)象B: 我們是朋友

participant C

Note right of C: 沒(méi)人陪我玩

4.4 甘特圖

title 項(xiàng)目開發(fā)流程

section 項(xiàng)目確定

需求分析 :a1, 2016-06-22, 3d

可行性報(bào)告 :after a1, 5d

概念驗(yàn)證 : 5d

section 項(xiàng)目實(shí)施

概要設(shè)計(jì) :2016-07-05 , 5d

詳細(xì)設(shè)計(jì) :2016-07-08, 10d

編碼 :2016-07-15, 10d

測(cè)試 :2016-07-22, 5d

section 發(fā)布驗(yàn)收

發(fā)布: 2d

驗(yàn)收: 3d

【注意：這個(gè)不是每個(gè)Markdown編輯器都支持的渲染功能（Cmd Markdown 的 gantt語(yǔ)法）】

%% 語(yǔ)法示例

gantt

dateFormat YYYY-MM-DD

title 軟件開發(fā)甘特圖

section 設(shè)計(jì)

需求 :done, des1, 2014-01-06,2014-01-08

原型 :active, des2, 2014-01-09, 3d

UI設(shè)計(jì) : des3, after des2, 5d

未來(lái)任務(wù) : des4, after des3, 5d

section 開發(fā)

學(xué)習(xí)準(zhǔn)備理解需求 :crit, done, 2014-01-06,24h

設(shè)計(jì)框架 :crit, done, after des2, 2d

開發(fā) :crit, active, 3d

未來(lái)任務(wù) :crit, 5d

耍 :2d

section 測(cè)試

功能測(cè)試 :active, a1, after des3, 3d

壓力測(cè)試 :after a1 , 20h

測(cè)試報(bào)告 : 48h

【注意：這個(gè)不是每個(gè)Markdown編輯器都支持的渲染功能（Typroa 的 mermaid語(yǔ)法）】

4.5 數(shù)學(xué)公式

這是單行公式$E=mc^2$

$\sin(\alpha)^{\theta}=\sum_{i=0}^{n}(x^i + \cos(f))$

$$ E=mc^2 $$

$$ \sin(\alpha)^{\theta}=\sum_{i=0}^{n}(x^i + \cos(f)) $$

5 注意事項(xiàng)

5.1 空格問(wèn)題

Markdown對(duì)空格是不敏感的，也就是說(shuō)你想輸入空格顯示的時(shí)候，還需要特殊操作，比如首行空兩個(gè)的寫作場(chǎng)景。

? 半角的空格 ? 全角的空格

5.2 換行問(wèn)題

操作方法

行尾打兩個(gè)或兩個(gè)以上的空格之后回車（換行后的行距較小）

打兩個(gè)回車 （換行之后的行距變大）

html的
來(lái)?yè)Q行 （比較兼容的寫法）

這是一行
這是另一行 這是第3行

這是一行

這是另一行

這是第3行

這是一行
這是另一行
這是第3行

5.3 字符轉(zhuǎn)義的問(wèn)題

在 HTML 文件中，有兩個(gè)字符需要特殊處理： < 和 & 。 < 符號(hào)用于起始標(biāo)簽，& 符號(hào)則用于標(biāo)記 HTML 實(shí)體，如果你只是想要使用這些符號(hào)，你必須要使用實(shí)體的形式，像是 < 和 &。

這里舉兩個(gè)例子：

AT&T AT&T

4 < 5 4 < 5

5.4 內(nèi)嵌 HTML 標(biāo)簽的問(wèn)題

我也不熟，很少有，舉個(gè)例子：

這是紅色字體

這是綠色字體

字體大小size=1

字體大小size=3

字體大小size=5

【注意：以上html標(biāo)簽有些編輯器又不支持】



審核編輯：劉清