All Things Markdown

https://javachen.github.io/

1. 概述
2. 特点
3. 语法
4. 编辑器
5. 浏览器插件
6. 实现版本
7. 参考资料

Markdown 是一种轻量级标记语言，创始人为约翰·格鲁伯（John Gruber）和亚伦·斯沃茨（Aaron Swartz）。它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML(或者HTML)文档”。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

兼容 HTML

要在Markdown中输写HTML区块元素，比如<div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其它内容区隔开，还要求它们的开始标签与结尾标签不能用制表符或空格来缩进。Markdown 的生成器有足够智能，不会在 HTML 区块标签外加上不必要的 <p> 标签。

例子如下，在 Markdown 文件里加上一段 HTML 表格：

请注意:

• 在 HTML 区块标签间的 Markdown 格式语法将不会被处理。
• HTML 的区段（行内）标签如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。

特殊字符自动转换

Markdown会对一些特殊字符进行转化，如：&、©、<、>,如果<、>用作html标签的界定符，则不会对其转换。

不过需要注意的是，code 范围内，不论是行内还是区块， < 和 & 两个符号都一定会被转换成 HTML 实体。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

类 Atx 形式则是在行首插入 1 到 6 个 # ，对应到标题 1 到 6 阶，例如：

你可以选择性地「闭合」类 atx 样式的标题，这纯粹只是美观用的，若是觉得这样看起来比较舒适，你就可以在行尾加上 #，而行尾的 # 数量也不用和开头一样（行首的井字符数量决定标题的阶数）

类 Setext 形式是用底线的形式，利用 = （最高阶标题）和 - （第二阶标题），例如：

任何数量的 = 和 - 都可以有效果。

强调

Markdown 使用星号（*）和底线（_）作为标记强调字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围，用两个 * 或 _ 包起来的话，则会被转成 <strong>，例如：

断行

如果你真的想在Markdown中插入换行标签<br/>，你可以在行尾输入两个或以上的空格，然后回车。 这样插入换行十分麻烦，但是“每个换行都转换为<br/>”在 Markdown中并不合适，所以只在你确定你需要时手动添加。

列表

Markdown 支持有序列表和无序列表。

无序

无序列表使用星号、加号或是减号作为列表标记：

有序

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

很重要的一点是，你在列表标记上使用的数字并不会影响输出的 HTML 结果。

如果你的列表标记写成：

或甚至是：

你都会得到完全相同的 HTML 输出。

注意：

• 如果列表项目间用空行分开，在输出 HTML 时 Markdown 就会将项目内容用 <p> 标签包起来
• 列表项目可以包含多个段落，每个项目下的段落都必须缩进 4 个空格或是 1 个制表符
• 如果要放代码区块的话，该区块就需要缩进两次，也就是 8 个空格或是 2 个制表符

区块引用

Markdown 标记区块引用是使用类似 email 中用 > 的引用方式。

Markdown 也允许你偷懒只在整个段落的第一行最前面加上 >

区块引用可以嵌套（例如：引用内的引用），只要根据层次加上不同数量的 > ：

引用的区块内也可以使用其他的 Markdown 语法，包括标题、列表、代码区块等：

分隔线

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线：

代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 标签来把代码区块包起来。

要在 Markdown 中建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以

内联代码

链接

Markdown 支持两种形式的链接语法： 行内式和参考式两种形式。

不管是哪一种，链接文字都是用 [方括号] 来标记。

要建立一个行内式的链接，只要在方块括号后面紧接着圆括号并插入网址链接即可，如果你还想要加上链接的 title 文字，只要在网址后面，用双引号把 title 文字包起来即可，例如：

参考式的链接**是在链接文字的括号后面再接上另一个方括号，而在第二个方括号里面要填入用以辨识链接的标记：

你也可以选择性地在两个方括号中间加上一个空格：

接着，在文件的任意处，你可以把这个标记的链接内容定义出来（注意去掉冒号前面空格）：

引用本地资源，可以使用相对路径：[about me](/about/)

隐式链接标记功能让你可以省略指定链接标记，这种情形下，链接标记会视为等同于链接文字，要用隐式链接标记只要在链接文字后面加上一个空的方括号，如果你要让 “Google” 链接到 google.com，你可以简化成：

然后定义链接内容（注意去掉冒号前面空格）：

由于链接文字可能包含空白，所以这种简化型的标记内也许包含多个单词：

然后接着定义链接（注意去掉冒号前面空格）：

链接的定义可以放在文件中的任何一个地方，我比较偏好直接放在链接出现段落的后面，你也可以把它放在文件最后面，就像是注解一样。

下面是一个参考式链接的范例（注意去掉冒号前面空格）：

如果改成用链接名称的方式写（注意去掉冒号前面空格）：

图片

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

行内式的图片语法看起来像是：

详细叙述如下：

• 一个惊叹号 !
• 接着一个方括号，里面放上图片的替代文字
• 接着一个普通括号，里面放上图片的网址，最后还可以用引号包住并加上 选择性的 ‘title’ 文字。

参考式的图片语法则长得像这样：

「id」是图片参考的名称，图片参考的定义方式则和连结参考一样（注意去掉冒号前面空格）：

到目前为止， Markdown 还没有办法指定图片的宽高，如果你需要的话，你可以使用普通的 标签。

自动链接

Markdown 支持以比较简短的自动链接形式来处理网址和电子邮件信箱，只要是用方括号包起来， Markdown 就会自动把它转成链接。一般网址的链接文字就和链接地址一样，例如

Markdown 会转为：

邮址的自动链接也很类似，例如：

Markdown 会转成：

反斜杠

Markdown 可以利用反斜杠来插入一些在语法中有其它意义的符号，例如：如果你想要用星号加在文字旁边的方式来做出强调效果（但不用 <em> 标签），你可以在星号的前面加上反斜杠：

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号：

表格

使用语法解释引擎 Redcarpet(需要开启tables选项)，则表格如下定义：

其中:所在位置表示表格的位置对齐

添加 table thead tobody th tr td 样式后显示的效果是：

row1text1	row1text3	row1text3	row1text4
row2text1	row2text3	row2text3	row2text4

Github中定义表格方式如下：

显示的效果如下：

Content from cell 1	Content from cell 2
Content in the first column	Content in the second column

作为一种小型标记语言，Markdown很容易阅读，也很容易用普通的文本编辑器编辑。另外也有一些编辑器专为Markdown设计，可以直接预览文档的样式。下面有一些编辑器可供参考：

• Cmd Markdown 支持实时同步预览，区分写作和阅读模式，支持在线存储，分享文稿网址。
• Dillinger.io 一个在线Markdown编辑器，提供实时预览以及到 GitHub 和 Dropbox 的拓展连接。
• notepag 另一个在线Markdown编辑器，支持实时预览，提供临时网址和和密码，可以分享给其他人。
• Mou 一个Mac OS X上的Markdown编辑器。
• MarkdownPad a full-featured Markdown editor for Windows.
• WMD a Javascript WYSIWYM editor for Markdown (from AttackLab)
• PageDown 一个Javascript WYSIWYM Markdown编辑器 (来自 StackOverflow)
• IPython Notebook 以ipython为后台，利用浏览器做IDE，支持MarkDown与LaTex公式。
• http://mahua.jser.me/ 一个在线编辑markdown文档的编辑器
• http://markable.in/editor/ A remarkable online markdown editor
• OsChina OsChina在线编辑器
• Logdown 是台湾一个博客写手和开发者在一个周末和三位朋友在24小时之内做的一个Hackathon 項目。这是一个支持Markdown的博客写作平台。在国际上也引起关注。它的写作界面是单栏宽屏。
• <jianshu.io> 这是一个支持Markdown的中文写作社区。
• 有记 | noteton 有记提供基于云笔记服务的博客发布平台。

• MaDe (Chrome)
• Markdown Here (Chrome, Firefox, Safari, and Thunderbird)
• Poe: Markdown Editor (Chrome)
• MarkDown (Chrome)
• StackEdit (Chrome)
• 扩展程序Markdown Preview Plus (Chrome)

由于Markdown的易读易写，很多人用不同的编程语言实现了多个版本的解析器和生成器。下面是一个按编程语言排序的实现列表。

• C
  • Sundown, 一个用C写的Markdown实现。
  • Discount, 一个Markdown标记语言的C语言实现版本。
  • peg-markdown, 一个用C写的，使用了PEG (parsing expression grammar)的Markdown实现。
• Java
  • MarkdownJ the pure Java port of Markdown.
  • Pegdown, a pure-Java Markdown implementation based on a PEG parser
  • MarkdownPapers, Java implementation based on a JavaCC parser
  • Txtmark, another Markdown implementation written in Java
• Lua
  • Markdown.lua, a Markdown implementation in Lua
  • Lunamark, a markdown to HTML and LaTeX converter written in Lua, using a PEG grammar
• PHP
  • PHP Markdown and Markdown Extra
  • Markdown Viewer for PHP, allows the viewing of a Mardown doc via a local PHP server (a wrapper for PHP Markdown)
• JavaScript
  • Uedit, a Javascript “WYSIWYM”
    editor for Markdown
  • Strapdown.js - JavaScript客户端解析markdown内容为html
  • Marked - Fast Markdown parser in JavaScript
• Python
  • Markdown in Python, A Python implementation of Markdown
  • Misaka, a Python binding for Sundown.
• Ruby
  • BlueCloth, an implementation of Markdown in Ruby
• Scala
  • Knockoff, a Markdown implementation written in Scala using Parser Combinators
  • Actuarius, another Markdown implementation written in Scala using Parser Combinators
• GO
  • Blackfriday, another Markdown implementation written in Go
• 其它
  • MarkdownSharp, a slightly modified C# implementation of the Markdown markup language. Developed and used by Stack Overflow.
  • Markdownr.com, a simple website to preview markdown in real time
  • Pandoc, a universal document converter written in Haskell
  • ReText, an implementation for Markdown and reStructuredText.

其他资料

• Markdown+R写作

• [1] 维基百科 Markdown
• [2] Markdown 语法说明 (简体中文版)
• [3] GitHub Guides:Mastering Markdown
• [4] Daring Fireball
• [5] Markdown在线写作速成

原文:大专栏  All Things Markdown