markdown

更改历史

* 2017-11-17    高天阳    标准化文档内容
* 2017-09-08    高天阳    初始化文档

1 历史、现状和发展

Markdown 是一个 Web 上使用的文本到HTML的转换工具，可以通过简单、易读易写的文本格式生成结构化的HTML文档。

Markdown 的目标是实现「易读易写」。

Markdown具有一系列衍生版本，用于扩展Markdown的功能（如表格、脚注、内嵌HTML等等），这些功能原初的Markdown尚不具备， 它们能让Markdown转换成更多的格式，例如LaTeX，Docbook。 Markdown增强版中比较有名的有Markdown Extra、MultiMarkdown、 Maruku等。 这些衍生版本要么基于工具，如Pandoc；要么基于网站，如GitHub和Wikipedia，在语法上基本兼容，但在一些语法和渲染效果上有改动。

Markdown的语法简洁明了、学习容易，而且功能比纯文本更强，因此有很多人用它写博客。 世界上最流行的博客平台WordPress和大型CMS如Joomla、 Drupal都能很好的支持Markdown。完全采用Markdown编辑器的博客平台有Ghost和Typecho。

用于编写说明文档，并且以“README.MD”的文件名保存在软件的目录下面。

除此之外，现在由于我们有了RStudio这样的神级编辑器，我们还可以快速将Markdown转化为演讲PPT、Word产品文档、 LaTex论文甚至是用非常少量的代码完成最小可用原型。在数据科学领域，Markdown已经被确立为科学研究规范， 极大地推进了动态可重复性研究的历史进程。

2 安装和使用

2.1 安装

任何一个编辑器 均可使用markdown语法编写md格式文件。

• 简书版教程

• csdn版教程

• 详细版教程

2.2 使用

2.3 示例

2.3.1 标题

• 类Setext

This is an H2

  Code:

  This is an H1   
  ====

  This is an H2
  ----

备注:任何数量的=和-都可以有效果<br/>
=表示最高阶标题,-表示第二阶标题

• atx形式

This is an H2

This is an H3

This is an H4

This is an H5

This is an H6

  Code:

  # This is an H1

  ## This is an H2

  ### This is an H3

  #### This is an H4

  ##### This is an H5

  ###### This is an H6

也可以表示成这样 # This is an H1 #
备注: 行首n个#表示n阶标题，n最大为6

2.3.2 列表

• 有序列表

有序列表使用数字接着一个英文句点

1. Bird
2. McHale

 Code:

 1. Bird
 2. McHale

无序列表

无序列表是使用*,+,-中任意一种来表示

• Red
• Green
• Blue

  Code:
  - Red
  + Green
  * Blue

2.3.3 引用

区块引用是使用类似email中用>来表示

简单引用1 简单引用2

多行引用

嵌套引用

引用中使用Markdown语法。

1. 这是第一行列表项。
2. 这是第二行列表项。

给出一些例子代码：

return shell_exec("echo $input | $markdown_script");

Code:
 > 简单引用1
 > 简单引用2
 > 
 > 多行引用
 >> 嵌套引用

 > ## 引用中使用Markdown语法。
 > 
 > 1.   这是第一行列表项。
 > 2.   这是第二行列表项。
 > 
 > 给出一些例子代码：
 > 
 >     return shell_exec("echo $input | $markdown_script");

2.3.4 代码区块

建立代码区块,只需要简单地缩进4个空格或是1个制表符就可以

代码块一直持续到没有缩进的那一行(或是文件的结尾)

代码块

也可以使用` 来表示

使用缩进表示代码块

2.3.5 分隔线

一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西, 也可以在星号或是减号中间插入空格

---

- - -

***

 * * *

 ——————————————

——————————————

2.3.6 段落和换行

• 段落

段落是由一个或多个连续的文本行组成,

它的前后要一个以上的空行(显示上看起来像是空的)

• 换行

Mardown允许段落内的强迫换行(插入换行符)
要依赖Markdown来插入<br/>标签的话,在<br/>插入处要先按入两个以上的空格然后回车

2.3.7 链接

支持两种形式的连接语法: 行内式和参考式 链接字符不区分大小写

• 行内式

  This is baidu

  baidu

Code:
This is [baidu](http://www.baidu.com/ "度娘")

[baidu](https://www.baidu.com/)

• 参考式

  This is baidu example reference-style link.

Code:
This is [baidu example][id] reference-style link.
标记: [id]: https://www.baidu.com/ "度娘"
或者: [id]: https://www.baidu.com/ '度娘' 
或者 [id]: https://www.baidu.com/ (度娘)

• 隐式链接标记功能

[Baidu][] 标记可以这样写: [Baidu]: http://baidu.com

Code:
[Baidu][]
标记可以这样写: [Baidu]: http://baidu.com

• 参考式链接范例:

--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"
(备注: 上述代码在使用时需删掉前面的--)

• 自动链接

  https://www.baidu.com

Code:

http://www.baidu.com

2.3.8 强调

Markdown使用性星号()和底线(_)作为标记强调字词的符号 两端被一个或包围的单词会被转换成斜体 两端被两个*或包围的单词会被转换成粗体 *或_的两端不能有空白 用什么符号就以什么符号结尾

斜体

斜体

粗体

粗体

加粗斜体

删除线

Code:
 *斜体*
 _斜体_
 **粗体**
 __粗体__
 ***加粗斜体***
 ~~删除线~~

2.3.9 代码

如果要标记一段行内代码,可以用反引号 ` 把它包起来 用多个反引号来开启和结束代码区段

段落代码
包含`反引号 包含 `两个反引号` <特殊符号&>

 Code:

 ``段落代码``  
 ``包含`反引号``
 ``包含 `两个反引号` `` 
 ``<特殊符号&>``

2.3.10 图片 Markdown使用一种和链接很相似的语法来标记图片 允许两种样式:行内式和参考式

• 行内式的图片语法:

Code:
![September](http://p3.pstatp.com/origin/46e70001ab09e82f1f36)  
![拍下过记住过好过拥有](http://p3.pstatp.com/origin/46e70001ab09e82f1f36 "摄脉")

• 参考式语法:

Code:
--![拍下过记住过好过拥有][xd]  
--[xd]:http://p3.pstatp.com/origin/46e70001ab09e82f1f36 "摄脉"
(备注: 上述代码在使用时需删掉前面的--)

2.3.11 转义

使用反斜杠来插入一些在语法中有其它意义的符号,如* 需要转义的字符:

\   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

2.3.12 锚点

网页中，锚点其实就是页内超链接，也就是链接本文档内部的某些元素，实现当前页面中的跳转。 比如我这里写下一个锚点，点击回到目录，就能跳转到目录。 在目录中点击这一节，就能跳过来。 还有下一节的注脚。这些根本上都是用锚点来实现的。

注意:

1. Markdown Extra 只支持在标题后插入锚点，其它地方无效。
2. Leanote 编辑器右侧显示效果区域暂时不支持锚点跳转，所以点来点去发现没有跳转不必惊慌，但是你发布成笔记或博文后是支持跳转的。

语法描述： 在你准备跳转到的指定标题后插入锚点{#标记}，然后在文档的其它地方写上连接到锚点的链接。

跳转到示例

## 0. 目录{#index}
跳转到[目录](#index)

2.4 最佳实践

难点：最佳实践，超出于示例，应该归纳总结出积累的技巧。

3 同类技术对比

难点：归纳比对项

Markdown

• 优点:
  • 格式简单，即使在纯文本模式下也很易读。
  • 应用广泛。在 GitHub, Reddit, StackOverflow 等一大批网站的影响下，在互联网上应用很广。
  • 工具和库的支持很好。无论是编辑、转换还是和其它库的集成，Markdown无疑在三种中是最好的。
• 缺点:
  • 不支持复杂的格式（如表格等）。
  • 有太多不兼容的方言。由于原始的Markdown支持的格式有限，所以出现了很多不同的扩展，这些扩展之间的不兼容性是一个问题。 GitHub 等几个公司准备制定一个统一的标准，希望这种情况能有所好转。

reST

• 优点:
  • 表达能力强。如果要写书、文档等复杂格式的内容，reST 无疑是一个很好的选择。
  • 和Python语言的结合较好。如果你是Python程序员，reST也是文档的首选。
  • 有Sphinx这个很棒的工具支持，不但能转化成html、PDF等各种格式，还支持python、javascript、C++等编程语言，并且有很多的扩展。
• 缺点:
  • 格式过于复杂。reST纯文本的可读性不如Markdown和Org.
  • 工具和库不如Markdown丰富。 Org
• 优点:
  • 有最好的编辑器支持(如果你用Emacs的话). 在Emacs的org-mode模式下编辑Org非常舒服。
  • 功能强大。除了一般的格式，还支持「文学编程」、GTD 等。并且能够导出为各种格式。
• 缺点:
  • 跟Emacs结合紧密。如果你不是一个Emacs用户，那么很遗憾你不能享受Org的所有便利（即使vim已经对Org有了基本的支持）。
  • 缺少各种库的支持。你要是想把Org集成到你的系统里可能没有那么容易。
  • 格式复杂。功能的强大往往伴随着更多要学习的东西。

总结如果要集成到你的系统里（比如用户评论），或者写格式不是太复杂的博客，Markdown也许是合适的选择。 如果要写复杂的文档，或者你是Python程序员，reST 有很大优势。 如果你是Emacs用户，或者要尝试下「文学编程」、GTD这些玩意儿，那么用org-mode吧!

参考资料

• 简书版教程
• csdn版教程
• 详细版教程
• Org-mode、reST、 Markdown 各有什么优缺点