轻量级标记语言Markdown

Markdown是一种轻量级标记语言(lightweight markup language)，用来写作简单的技术性文档非常便利。它是由John Gruber发明的，现在在Stack Overflow、BitBucket与Github等网站上都得到了使用。Markdown是文本格式的，语法非常简洁明了。

对于技术人员来说，使用Markdown编写技术文档很方便。我以前使用过Word写文档，使用过HTML写文档，当然也使用过无格式的文本文件写文档，还用UML图做过文档，但是现在我觉得，使用Markdown来写技术文档比它们都合适。

原因在于：

Markdown是文本格式的，非常适合保存在版本控制软件中，进行版本比较很方便。写文档也非常简单，不用专门的软件，任何一个文本编辑器都行
Markdown是有格式的，比无格式的文本文件结构性强太多
Markdown不需要非常繁琐的类似HTML的标签来控制格式，这些标签在书写的时候非常麻烦，在阅读的时候也非常干扰视线，让人无法流畅地阅读与写作

当你使用BitBucket或者GitHub来托管你的代码时，一般都可以在根目录下加入一个README.markdown，这样在别人通过浏览器查看你的项目时，BitBucket或GitHub就会在项目的首页上显示这个文件转化成的HTML，非常实用。

我们可以来比较一下同一个文档用HTML和Markdown来写分别是什么样的，例如下面的Markdown片段：

My software
====================

Markdown
--------------------

Markdown is a good language for writing tech docs, because:

* it's text
* it's clear
* it has clean format for reading and writing

Run python md2html.py -i input.md -o output.html to turn a markdown doc into a html.

对应的HTML文档是：

<h1>My software</h1></p> <p><h2>Markdown</h2></p> <p><p>Markdown is a good language for writing tech docs, because:</p></p> <p><ul><br /> <li>it's text</li><br /> <li>it's clear</li><br /> <li>it has clean format for reading and writing</li><br /> </ul></p> <p><p>Run <code>python md2html.py -i input.md -o output.html</code> to turn a markdown into a html.</p>

<h1>My software</h1>

<h2>Markdown</h2>

<p>Markdown is a good language for writing tech docs, because:</p>

<ul>

<li>it's clear</li>

<li>it has clean format for reading and writing</li>

</ul>

<p>Run <code>python md2html.py -i input.md -o output.html</code> to turn a markdown into a html.</p>

当然，Markdown也有一个缺点，直接浏览它的文本格式可能不是很漂亮，特别是如果要作为文档发布给别人看的时候。将其转化为HTML或者PDF格式之类文档的会更方便一些。市面上有一些免费软件可以做到这一点，例如Pandoc。Pandoc可以读取markdown、reStructureText、textile、HTML和LaTeX格式的文档，并将其转为PDF、DocBook、ePub、微软的docx、HTML、groff man page、OpenDocument、RTF、markdown、reStructureText、textile、AsciiDoc等一大堆的文档格式，非常强劲。我还为markdown转化为html做了一个pandoc.css，使用的时候只要pandoc your-markdown-file -o your-output.html -s -H pandoc.css即可。

另外，Markdown当然不可能实现HTML的每个标签，为了简洁性，它也丢掉了很多HTML的功能，但是对于技术文档写作来说，这已经完全够了。

Markdown也有很多在线编辑器，例如这个，还有这个。

就常见编辑器来说，vim有很多markdown的语法高亮插件，例如这个就不错。可是我Windows上常用的编辑器Notepad++就不支持Markdown了，虽然Github上有一个勉强可用的插件，但是这个插件只能算马虎能用，很不好使。当然，主要原因是Notepad++的自定义语言功能局限性较大，至少没有vim强导致的。还有一个不错的编辑器Sublime Text虽然支持markdown，但是支持也很弱，而且不支持GBK。

除此之外，Python、Perl、Java、PHP、C#等语言都有Markdown相应的解析或者转换模块，Python的这个Makrdown模块不错，不过因为它仅生成了HTML的片段，而且我们需要给其中的代码加上CSS样式，因此我做了一个md2html模块来封装它，最后生成的HTML是完整的HTML文件，编码使用UTF8，对应的代码的CSS是：

code {<br />     border: #dfdfdf 1px solid;<br />     padding: 1px 3px;<br />     background: #ffffe8;<br />     color: #444;<br />     font: 0.8em Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace;<br />     -webkit-border-radius: 3px;<br />     -moz-border-radius: 3px;<br />     border-radius: 3px;<br />     -moz-background-clip: padding;<br />     -webkit-background-clip: padding-box;<br />     background-clip: padding-box;<br />     display: inline-block;<br />     margin: 0px;<br /> }<br /> pre {<br />     margin-left: 4em;<br /> }

code {

border: #dfdfdf 1px solid;

padding: 1px 3px;

background: #ffffe8;

color: #444;

font: 0.8em Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace;

-webkit-border-radius: 3px;

-moz-border-radius: 3px;

border-radius: 3px;

-moz-background-clip: padding;

-webkit-background-clip: padding-box;

background-clip: padding-box;

display: inline-block;

margin: 0px;

}

pre {

margin-left: 4em;

}

这里是md2html对文章开头的markdown文件转化后生成的页面。

除了markdown之外，还有一些类似的轻量级标记语言，例如reStructureText、textile，还有AsciiDoc等。不过就简洁性和功能的平衡来说，markdown更让人满意一些，除此之外，markdown现在貌似也使用的更广泛一些。

P.S.一下，有了markdown做文字类的文档，那有时候需要画图怎么办呢？是否可以由一个文本文件生成图？这个时候，我们需要Graphviz，它可以由自定义的脚本语言来生成图，例如下面的脚本：

digraph git {
    graph [rankdir = "LR"];
    node [shape = "ellipse", fontcolor="gray", color = "gray"] master branch1;
    node [shape = "circle", fontcolor="black", color = "black"];

    c0 -> c1 -> c2 -> c3 -> c4 -> c5 -> c6;
    c3 -> c7 [label = "git checkout -b branch1", fontcolor = "gray"];
    c7 -> c8 -> c9;

    master -> c4 [color = "gray"];
    branch1 -> c7 [color = "gray"];
}

可以生成这样的图像：

不过Graphviz在精细排版上就没辙了，要做出商业化的图仍然不能指望它，只能使用Graphviz来做技术交流的图。