技术员博客      html  css  js  c++  java
  • 轻量级标记语言Markdown

    飞熊在天 | 知之者不如好之者,好之者不如乐之者 | 第 7 页


    轻量级标记语言Markdown

    Markdown是一种轻量级标记语言(lightweight markup language),用来写作简单的技术性文档非常便利。它是由John Gruber发明的,现在在Stack OverflowBitBucketGithub等网站上都得到了使用。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文档是:

    当然,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是:

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

    除了markdown之外,还有一些类似的轻量级标记语言,例如reStructureTexttextile,还有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 Demo

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

  • 相关阅读:
    无锁的并发编程
    Web 服务简介
    mod_proxy Apache HTTP Server
    WebKit的JavaScript对象扩展
    ASP.NET MVC3 快速入门第三节 添加一个视图
    StoneAge Dict 技术方案的可行性[1]
    mysql怎么创建,删除,查看索引?
    [Win32]Win32 SDK编程系列文章——键盘输入消息
    字符串系列——Immediate Decodability
    一步步带你做vue后台管理框架(一)——介绍框架
  • 原文地址:https://www.cnblogs.com/lexus/p/2472996.html
Copyright © 2011-2022 技术员博客