Markdown 是近年来十分流行的轻量标记语言,它使用了人类易懂且也容易输入的符号来编写文档,能够便利地撰写出不同等级的文档标题,还能加入图片、超链接,甚至是表格,完全符合一般文书的需求,软件界也是大量使用 Markdown 来撰写软件文档。大多数的 Markdown 编辑软件都可以将 Markdown 文档转换成 HTML 文档,方便文档的传播,这也是因为相同的 Markdown 文件在不同的 Markdown 编辑软件或是浏览软件所呈现出来的排版和样式可能不太一样,有些 Markdown 文档甚至还运用了 LaTeX 排版系统来撰写数学函数,但这并不是所有的 Markdown 软件都能够支持的。

Markdown to HTML Converter

「Markdown to HTML Converter」是笔者用 Rust 编程语言开发的 Markdown 文档转 HTML 文档的开源小工具,可以快速地将 Markdown 文档转成独立、可脱机单档打开的 HTML 文档,且支持代码高亮、MathJax(可以画数学函数,兼容 LaTeX)和 CJK 字体。产生出来的 HTML 文档所包含的 HTML 语法也都已有经过压缩。

安装 Markdown to HTML Converter

如果系统环境中有安装「Cargo」的话,可以直接使用以下指令来下载「Markdown to HTML Converter」的源代码项目,并进行编译安装。

cargo install markdown2html-converter

如果是使用 Linux 操作系统的话,可以直接到以下页面取得「Markdown to HTML Converter」的可执行文件,手动放置到 /usr/local/bin 目录中即可。网址如下:

使用 Markdown to HTML Converter

「Markdown to HTML Converter」的用法十分简单,只要输入一个 Markdown 文档的路径,程序就可以将这个 Markdown 文档转成 HTML 文档,并存放在同一个目录下。例如以下指令,可以将 README.md 转成 README.html,并存放在同一个目录下。

markdown2html-converter README.md

如果要指定输出的文件路径,可以加上 -o 选项。例如以下指令,可以将 README.md 转成 MyDoc.html,并存放在 /tmp 目录下。

markdown2html-converter README.md -o /tmp/MyDoc.html

预设的 HTML 标题为主文件名(不包含扩展名的文件名),如果要另外设置的话,可以加上 -t 选项。例如以下指令,可以将 README.md 转成 README.html,并存放在同一个目录下,README.html 的标题为 Document。

markdown2html-converter README.md -t Document

另外,如果有特殊需求的话,也还可以使用 --css-path、--highlight-js-path、--highlight-css-path、--mathjax-path-path 这些参数来分别指定 HTML 文档要嵌入的 CSS 样式、Highlight.js 的 JS 程序、Highlight.js 的 CSS 样式和 MathJax 的 JS 程序。

MathJax

如果要在 Markdown 文档中使用 MathJax 来画数学函数,如果是要嵌在一个文字段落中(inline),需使用 #{{ 和 }}# 将 MathJax 语法的部份括起来。而如果是要用在单独的段落中,需使用 #{{{ 和 }}}# 将 MathJax 语法的部份括起来。

范例

这个是一份范例的 Markdown 文档。其转出的 HTML 文档在这里。