[置顶] 献给写作者的 Markdown 新手指南

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

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

献给写作者的 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/

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 + 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 Distribution

The 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 许可协议进行许可。