markdown文檔，[置頂]獻給寫作者的 Markdown 新手指南

作者：http://jianshu.io/p/q81RER

出處：http://jianshu.io/p/q81RER

markdown文檔，

獻給寫作者的 Markdown 新手指南

簡書

「簡書」作為一款「寫作軟件」在誕生之初就支持了 Markdown，Markdown 是一種「電子郵件」風格的「標記語言」，我們強烈推薦所有寫作者學習和掌握該語言。為什么？可以參考:

• 『為什么作家應該用 Markdown 保存自己的文稿』。
• 『Markdown寫作淺談』

在此，我們總結 Markdown 的優點如下：

• 純文本，所以兼容性極強，可以用所有文本編輯器打開。
• 讓你專注于文字而不是排版。
• 格式轉換方便，Markdown 的文本你可以輕松轉換為 html、電子書等。
• Markdown 的標記語法有極好的可讀性。

當然，我們既然如此推崇 Markdown ，也必定會教會你使用 Markdown ，這也是本文的目的所在。不過，雖然?Markdown 的語法已經足夠簡單，但是現有的 Markdown 語法說明更多的是寫給 web 從業者看的，對于很多寫作者來說，學習起來效率很低，現在，我們特地為寫作者量身定做本指南，從寫作者的實際需求出發，介紹寫作者真正實用的常用格式，深入淺出、圖文并茂地讓您迅速掌握 Markdown 語法。

為了使您更好地學習，我們建議您登錄「簡書」，將您的編輯器切換至 Markdown 編輯器，新建一篇空白筆記，然后點擊右上角的預覽模式，此時，您的界面應當如下圖所示，左側為編輯區域，右側為預覽區域，您在左側輸入 Markdown 語法的文本，右側會立即幫您呈現最終結果，好了，讓我們開始學習吧~

簡書的預覽模式可以幫助你更快掌握 Markdown：

標題

這是最為常用的格式，在平時常用的的文本編輯器中大多是這樣實現的：輸入文本、選中文本、設置標題格式。

而在 Markdown 中，你只需要在文本前面加上?#?即可，同理、你還可以增加二級標題、三級標題、四級標題、五級標題和六級標題，總共六級，只需要增加?#?即可，標題字號相應降低。例如：

# 一級標題
## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題

注：#?和「一級標題」之間建議保留一個字符的空格，這是最標準的 Markdown 寫法。

你可以你的編輯器中嘗試輸入這六級標題，可以參考下方的截圖：

列表

列表格式也很常用，在 Markdown 中，你只需要在文字前面加上?-?就可以了，例如：

- 文本1
- 文本2
- 文本3

如果你希望有序列表，也可以在文字前面加上?1.?2.?3.?就可以了，例如：

1. 文本1
2. 文本2
3. 文本3

注：-、1.和文本之間要保留一個字符的空格。

列表案例截圖如下：

鏈接和圖片

在 Markdown 中，插入鏈接不需要其他按鈕，你只需要使用[顯示文本](鏈接地址)?這樣的語法即可，例如：

[簡書](http://jianshu.io)

在 Markdown 中，插入圖片不需要其他按鈕，你只需要使用?![](圖片鏈接地址)這樣的語法即可，例如：

![](http://ww4.sinaimg.cn/bmiddle/aa397b7fjw1dzplsgpdw5j.jpg)

注：插入圖片的語法和鏈接的語法很像，只是前面多了一個?！。

插入鏈接和圖片的案例截圖：

引用

在我們寫作的時候經常需要引用他人的文字，這個時候引用這個格式就很有必要了，在 Markdown 中，你只需要在你希望引用的文字前面加上?>?就好了，例如：

> 一盞燈， 一片昏黃； 一簡書， 一杯淡茶。 守著那一份淡定， 品讀屬于自己的寂寞。 保持淡定， 才能欣賞到最美麗的風景！ 保持淡定， 人生從此不再寂寞。

注：>?和文本之間要保留一個字符的空格。

最終顯示的就是：

一盞燈， 一片昏黃； 一簡書， 一杯淡茶。 守著那一份淡定， 品讀屬于自己的寂寞。 保持淡定， 才能欣賞到最美麗的風景！ 保持淡定， 人生從此不再寂寞。

引用的案例截圖：

粗體和斜體

Markdown 的粗體和斜體也非常簡單，用兩個?*?包含一段文本就是粗體的語法，用一個?*?包含一段文本就是斜體的語法。例如：

 *一盞燈*， 一片昏黃；**一簡書**， 一杯淡茶。 守著那一份淡定， 品讀屬于自己的寂寞。 保持淡定， 才能欣賞到最美麗的風景！ 保持淡定， 人生從此不再寂寞。

最終顯示的就是下文，其中「一盞燈」是斜體，「一簡書」是粗體：

一盞燈， 一片昏黃；一簡書， 一杯淡茶。 守著那一份淡定， 品讀屬于自己的寂寞。 保持淡定， 才能欣賞到最美麗的風景！ 保持淡定， 人生從此不再寂寞。

粗體和斜體的案例截圖：

結語

以上幾種格式是比較常用的格式，所以我們針對這些語法做了比較詳細的說明。除這些之外，Markdown 還有其他語法，如想了解和學習更多，可以參考這篇『Markdown 語法說明』。

強烈建議您現在就立馬用 Markdown 寫一篇文章吧，體會一下 Markdown 的優雅之處！

最后，希望我們的指南可以幫助到您，也希望「簡書」能夠成為您書寫 Markdown 的最佳選擇。

--------------------------------------------------------------------------------

PS:

怎么把作品設置置頂？使用 Markdown 插入本地圖片的時候，似乎不支持圖片格式擴展名前面再有點號，例如，在使用相對路徑插入本地圖片的時候，demo.jpg 可以成功顯示，而 demo.demo.jpg 就無法顯示了。

--------------------------------------------------------------------------------

轉自：http://www.tillage.net/the-markdown-language-used-by-github/

用markdown寫筆記，

Github 使用的 Markdown 語言

簡介

• 官方站點：http://daringfireball.net/projects/markdown/syntax
• 中文介紹：http://www.worldhello.net/gotgithub/appendix/markups.html
• 繁體中文：http://markdown.tw/
• 在線轉換：http://daringfireball.net/projects/markdown/dingus
• Github 在線轉換:http://github.github.com/github-flavored-markdown/preview.html

標題

支持六級標題

# 一級標題
## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題 ######

段落

• 空行分段
• 一個回車不分段，本行續上行。
• 行尾兩個空格保持換行

段落縮進

郵件體段落縮進：> 第一級段落縮進。
>
> > 第二級段落縮進。
>
> 返回一級段落縮進。

代碼塊

四個空格縮進是代碼塊

    $ printf "Hello, world.\n"

列表

無序列表

* 星號、減號、加號開始列表。- 列表層級和縮進有關。+ 和具體符號無關。* 返回一級列表。

有序列表

1. 數字和點開始有序列表。1. 注意子列表的縮進位置。1. 三級列表。1. 編號會自動更正。1. 二級列表，編號自動更正為 2。2. 返回一級列表。

列表段落

1. 列表項可以折行，對齊則自動續行。2. 列表項可包含多個段落。空行開始的新段落必須縮進四個空格，段落才屬于列表項。3. 列表中的代碼塊要縮進 8 個空格。$ printf "Hello, world.\n"

分割線

三條或更多短線（或星號、下劃線）\
顯示為分隔線。---

粗體和斜體

這些都是 **粗體** 或 __粗體__ ，
這寫都是 *斜體* 或 _斜體_ 。

刪除線

~~刪除線~~ 效果

下劃線

<u>下劃線</u> 效果

上標、下標

- Water: H<sub>2</sub>O
- E = mc<sup>2</sup>

等寬字體

行內反引號嵌入代碼，如: `git status` 。

鏈接

訪問 [Google](http://google.com "Search")
- 訪問 [GitHub][1]
- 訪問 [WorldHello][][1]: http://github.com "Git host"[worldhello]: http://www.worldhello.net

內部跳轉

<a name="md-anchor" id="md-anchor"></a>跳轉至 [文內鏈接](#md-anchor) 。

圖片

![GitHub](/images/github.png "Logo")GitHub Logo: ![GitHub][logo][logo]: /images/github.png "Logo"

混用 HTML

<div style="background:#bbb;">HTML 塊中不能混用 **標記語法**
</div>

• 本文固定鏈接:?http://www.tillage.net/the-markdown-language-used-by-github/
• 轉載請注明:?Lipvun?2012年12月02日 于?半畝方塘?發表

--------------------------------------------------------------------------------

markdown目錄語法？

Markdown寫作淺談

廢話

• 寫作會碰到什么難題？Markdown 如何解決的？
• 科技寫作會碰到什么難題？Markdown + R 如何解決的？
• 如何學習 Markdown + R ？
• 示范

1. 寫作與 Markdown

1.1 寫作會碰到什么難題？

寫作一般而言，會碰到這么一些難題：

• 難以專心：寫 Word 文檔的時候，我們經常浪費大量時間在 Word 本身上，特別是那 80% 我們用不到的功能。比如，找借口，Word 又出問題了；或者，又要升級了。其實，在內心偷笑，哈哈，可以偷懶了
• 浪費力氣在排版上：使用 Word 時，我們會花費大量力氣去排版，試圖讓文檔變得漂亮一些。是粗體還是斜體，是宋體還是黑體，對創作來說，有那么重要嗎？
• 難以自動的版本跟蹤：每一位自殺的寫作者的電腦文檔里面，都必然有一個 Word 文檔，從 V1.0 到 V20.0 的無數版本...
• 難以共同協作：想想你讓一位合作的編輯幫你改書有多么痛苦，一個 Word 文檔來，一個 Word 去，極其難用的修訂與審閱功能，你就理解了；

從 2009 年開始，我拋棄 Word 寫作，幾年來，幾本書、十萬字以上的長文檔，幾乎只是用 Word 在最后做個轉換與掃尾工作。剛開始是使用 google doc，然后當?Markdown?出現在視線之中后，毫不猶豫轉到它上面來了。

1.2 Markdown 是什么？

它實際上是個非常簡單、非常容易學習的語法。這個語法簡單到每個人都可以在 5 分鐘以內學會。應該是為數不多，你真的可以徹底學會的語言。

更重要的是，Markdown 語法所有要素，是與寫作的習慣一脈相承的，套用句俗語：僅為寫作而生。比如：

• 要寫引用網址了，就是這么寫 [] 再加個 ()，如：豆瓣
• 要引用大段文字，就是直接 > 后面寫引用，如 ：

習慣是人生最大的指導。

• 2 個表示標題二級別，3 個 # 號表示標題三級別。例如：## ###，分別就代表標題二、標題三
• 要寫列表了，就直接 * * * ，分行下來
• 要強調什么內容了，直接在強調的內容前后加個，如：強調的內容?要加粗，則 2個?號，如：加粗的內容

一切就這么簡單。Markdown 之所以在被鼓吹之后，越來越流行，不是因為它復雜，而是因為它足夠簡單。

1.3 Markdown 如何解決這些難題的？

Markdown 誕生于互聯網時代，更是由深諳互聯網文本之道的?John Gruber?等人設計。因為?Ruby 與 github 圈的極客們的熱捧，以及來自?github、Stackoverflow?等的大力支持。從一開始，就建立一個完整的生態鏈。我們可以粗略看看，Markdown 如何解決這些難題的。感興趣的朋友可以去讀我的老文：理想的寫作環境：git + github + markdown + jekyll

1.3.1 借助于 github 解決文檔共享與版本自動跟蹤問題

Word 共享難？我的所有文檔都放在 github 或者其他支持 git 版本跟蹤服務的服務器上。所以，可以極其方便的共享文檔寫作過程。看看，最近在與豆瓣友鄰協作的一本書的截圖：

可以清晰地看到，我的所有寫作過程，github 都可以自動記錄下來，從而不再擔心寫廢。另一位豆瓣友鄰的任何改動、編輯的修訂意見，大家都可以實時完成，也具備歷史跟蹤與版本查找功能。

1.3.2 Markdown 讓我們專注寫作，而不是關注排版

在用 Word 寫作的時候，經常浪費大量時間去思考排版，但是因為 Markdown 足夠簡單，你無法思考排版，也沒必要思考，所以，逼自己集中精力寫作。Markdown 語法因為格式足夠簡單，所以，導致開發者非常容易生成漂亮的版式，一切既有的 CSS 都可以簡單修改之后套用，如：css 1?、css 2

這是我在寫的一篇長篇科普文章。大家可以看到，我左邊寫，右邊就是非常漂亮的稿件出來了。同樣，值得驕傲的是，這個寫作軟件，在世界范圍，廣受好評的?Mou，也是另一位國人 Chen Luo 開發的 :D 我們為這個時代，類似于 yihui 與 Chen Luo, 這批安靜的創作者而驕傲。

2. 科技寫作與Markdown+R

2.1 科技寫作會碰到什么難題？

如果你是純文科生，寫的都是豆瓣小酸文或者詩歌之類的，那么，看完上面這一部分就可以打住了。如果你還有寫科技論文的需要，則繼續往下看。

科技寫作與文藝寫作的不同主要有：

• 公式與圖表：相信各位寫過科學論文的，都會為數學公式與各類圖表的輸出頭疼不已；
• 格式轉換：pdf 是通用的，但是有時偏偏需要 LaTeX 原始格式或者 Word 原始格式；
• 參考文獻：投稿給不同刊物，往往參考文獻要根據對方的格式來調整。

解決這些難題，LaTeX?是國際科學界，尤其是偏數理類的學科的主流方案之一。當然，因為中國盜版 office 的流行，導致國內科技論文 Word 更盛行，則是另一碼事。Word 因為近些年在參考文獻協作軟件、數學公式方面的發力，也逐步成為科技界認同的論文投遞標準之一。

提到 LaTeX 的人們，常常有兩種口氣。一種是當做大神來敬仰的，當語言、軟件變為傳奇，路人皆知它的誕生歷史時，于是，眾多如你我這類文科生，只有抬頭仰望的份了。另一類，則是不屑的口氣，LaTeX 那么好學，你怎么都學不會！國際期刊都是用這個寫的，你別混了。。。

于是，我等文科生只好在被鄙視的眼光之下，快快走過 LaTeX。。。但是，LaTeX 真的符合人們寫作習慣嗎？請記住當時的歷史。那時的計算機，所見即所得，并不像今天這么流行。那時的計算機，處理能力也不像今天這么強大。更別提什么腳本語言了。翻出上一份 LaTeX 文檔所用的 APA 模版，大家就知道它有多么坑爹了。。。

使用?Lyx，好看多了。問題是，它有坑嗎？你跳過嗎？

2.2 Markdown + R 如何解決的？

每位試圖解決 LaTeX 的不便，又試圖保留它的優點的人們，都走上了一條不歸路。

直到有一天，極其熟悉 LaTeX，也熟悉 Markdown 的 yihui 同學，意識到了，LaTeX 它可以作為最終格式生成。但是，我們中間的寫作過程，完全可以用 Markdown 這么簡單明了的語法來寫，我們真正需要的，就是一堆數學公式、圖表與參考文獻而已。前 2 者，恰恰是 R 的強項。后者，則留給開源社區，下一步解決。（可參考線索 1、線索 2、線索 3?)

于是，在他的新作 R 包?knitr?中，果斷提供了 Markdown 支持。并說服 R 社區主流編輯器廠家，開源軟件?RStudio?提供 ?Markdown 支持，從而使得 Rmd 這種新格式開始流行。我們有幸看到這個重要格式的誕生，國人的貢獻如此重要。

2.3 Rmd 簡介

Rmd 格式更詳細的描述，讀 ?yihui 的文檔：自動化報告

在這里，讓我簡單說明，如何最快上手 Rmd 格式。

2.3.1 安裝并配置 RStudio

下載?RStudio?之后，打開配置選項，如下圖所示：

然后，進行如下配置：

2.3.2 新建 Rmd 文檔

新建一個 Rmd 文檔，如下圖所示：

然后，默認會出來一些內容。如果你對 Markdown 語法有不熟悉的地方，點擊 MD 按鈕。寫完之后，直接點擊：?Knit HTML?按鈕即可發布。MD 按鈕與 Knit Html 按鈕的位置如下圖所示：

就會預覽成功。你也可以點擊保存，生成相應的圖片、Markdown 文檔。

是的，你要的一切圖片都有了！這就是 yihui 所推崇的 文學性編程、可重復研究概念的神奇。

更重要的是，還保留了對 LaTeX 的無縫兼容。比如，大家可以敲下這段文字：

## The Normal DistributionThe normal distribution is defined as follows:$$latex
f(x;\mu,\sigma^2) = \frac{1}{\sigma\sqrt{2\pi}} e^{ -\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2 }
$$To generate random draws from a normal distribution we use the **rnorm** function:```{r block1}
output <- rnorm(1000, 100, 15);
```The normal distribution has the typical bell shape:```{r block2, fig.width=8, fig.height=5}
ggplot2::qplot(output)
```

其中，這一段，

$$latex
f(x;\mu,\sigma^2) = \frac{1}{\sigma\sqrt{2\pi}} e^{ -\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2 }
$$

就是直接生成 LaTeX 格式的數學公式！

沒有安裝 RStudio，或者不熟悉 R 的朋友，可以在我搭建的一個在線演示 APP 里面，將上述代碼，粘貼上去，然后看看神奇的效果！

網址是：R Markdown App?效果如下圖所示：

2.4 這么做，有什么好處呢？

讓我細數一下：

2.4.1 真正意義上的可重復性研究

發表論文或者審核同事的報告，有個最麻煩的事情，你不知道他的步驟或者計算是否有誤。現在，代碼嵌在報告正文中，或者附錄在報告末尾。而你，要做的，僅僅是一鍵生成。。。 這就是真正意義上的可重復性研究！

2.4.2 更強大的數學與制圖能力

既兼容了 LaTeX 的既有能力，同時，又廣泛借助于 R 自身強大的作圖與統計學習能力。

更重要的是，未來，并不是非要用 R 語言作圖。yihui 同學在前文中的描述已經極其清楚了。

2.4.3 當然，還有云計算

真正意義上的云計算，尤其是類似于我們這樣，中小企業、小型實驗室實戰使用的小型云計算，不同于各類忽悠的云計算。Markdown + R 這種方式是最佳方式之一。上述例子中提到的那個 APP，就是搭建在云中。同時提供各類 REST 接口，可以被 Ruby 程序調用。

2.5 Markdown 格式與 LaTeX、Word 等格式的互轉

點這里：Pandoc

還有不少有趣的玩法，如?Building a beamer presentation with knitr.

3. 如何學習 Markdown + R ？

好了，回到大家最關心的部分。分成兩部分，先是如何學習 Markdown，其次是如何學習 R。

3.1 Markdown 格式說明

• 參考：Markdown
• 更好的學習辦法是直接讀各類范本文件
• 更多資源參考?V2ex節點

3.2 Markdown 編輯器

• Mac 等平臺下推薦?Mou
• Windows 平臺推薦?MarkdownPad
• RStudio 可作為寫作科技論文與R語言編輯器選擇，它是跨平臺的
• markdown-here?借助 Chrome 插件，將 gmail 寫作窗口變為 Markdown 在線寫作窗口
• 可以直接在線通過 github 撰寫與提交 Markdown 文件，github 有自動的版本跟蹤功能，不用擔心寫廢與找不到以前寫的

3.3 Windows 下的 GitHub 特別說明

• 如果碰到 git、github 等與 windows 不兼容的現象，不建議折騰，而是直接在線提交即可。
• GitHub 最近發行了 Windows 版本，下載地址在這里
• 我的老文：如何高效利用 github

3.4 如何學習 R

3.4.1 Rstudio

• Getting_Started_with_RStudio.pdf

3.4.2 R 語言入門讀物

• R for SAS and SPSS Users.pdf ： 適合有 SPSS 基礎的朋友
• Analysis of Questionnaire Data with R ： 適合處理問卷數據的文科生或社會科學類
• 更多參考我的豆列：技術派心理學

4. 示范

4.1 文藝青年

文藝青年看這里，

• 為什麼文科生也該用 markdown 寫作?
• 為什么作家應該用 Markdown 保存自己的文稿

4.2 科學青年

可以看這里：如何學習科學：開放科學工具箱

點擊?RAW?即可看到原始格式。這是一個長文檔的示范。另一個示范是作者寫的一個在線 DEMO：

云中的社會網絡分析 + Markdown

以及：Markdown + R 科技文寫作

4.3 技術青年

• knitr?以及各類 Google、維基百科。
• 特別是：pandoc-markdown
• Primarily Pandoc: Writing in Markdown instead of LaTeX

本作品采用知識共享署名-非商業性使用-禁止演繹 3.0 Unported 許可協議進行許可。