1 前言

经常需要写一些markdown文档，用vscode或者vim的MarkdownPreview插件都能实现比较好的实时渲染与编辑，但导出给别人看时发现存在一个问题：没有目录栏，文档很长时翻起来十分费劲。（vscode的导出功能我没怎么用，好像挺鸡肋就放弃了；vim的话我是直接用谷歌浏览器的SingleFile插件保存渲染的html）
查了一下发现有位叫i5ting的大佬很早开发过一个叫i5ting_ztree_toc的工具，能够为markdown转html后生成目录并且自动编号，正好是我想要的东西。用了一会发现还不够满足自己的需求，主要有以下几点不足：

1) 生成的html需要和一堆样式文件(.css、.js)所在的文件夹放一起；
2）目录栏随滚动高亮功能不错，但有图片、uml等元素时正在浏览区域与高亮条目明显对应不起来；
3）不支持LaTeX公式；
4）不支持各种图（mermaid、plantuml…）；
5）默认marked渲染器配置不全，高亮没有；

综上所述，还是自己动动手修改吧。于是有了md2html这个工具：

2 md2html

首先几个足够展示markdown与LaTeX几乎所有常用语法的demo：

basicTest
katexSupportTest
latexTest1
latexTest2

这个工具的设计原则有如下两点：

• 完全本地化，所有内容不需要联网便可舒适阅览
• 只能有一个html文件，所有样式文件必须内嵌进去，不能通过联网或本地其他文件的方式获取

主要特性:

1）目录侧边栏与自动编号，以及定位高亮；
2）markdown中本地图片路径(如![](img/a.png))可转为base64内嵌入html，不再需要img文件夹；（可禁用该转换）
3）plantuml支持，可选择使用plantuml.jar生成.svg到本地再转为base64嵌入html；
4）mermaid支持，这个比较容易实现；
5）flowchart.js支持(一种画流程图的)，我没怎么用过，不过也比较容易实现；
6）本地化KaTeX支持（一开始用Mathjax但感觉最新版很难弄进一个html里就放弃了），所有字体手动转为base64嵌入了html中；

3 使用建议

1）默认不使用本地plantuml.jar（生成速度慢一些），默认转换图片为base64；
2）使用mdhtml -h查看帮助：

$ md2html -h
Usage: md2html can convert markdown(.md) file to single html file(offline), which is a modified tocmd.npm(a npm wrapper of i5ting_ztree_toc) tool

Options:
  -V, --version                output the version number
  -i, --intputfile <filename>  .md file location, default is README.md  (default:
                               "README.md")
  -o, --output-path <path>     output .html PATH, default PATH is the same with .md file
  -d, --debug                  print detailed information(for debug)
  -n, --no-convert-img         don't convert local images to base64 when generating .html
                               file
  -u, --uml-path [path]        plantuml.jar PATH to generate offilne UML images(require
                               java!), default PATH is ./pantuml.jar
  -h, --help                   display help for command

3）推荐Linux系统，或者WSL也行。Windows下用cmd也太难受了
4）目前pkg打包后的windows版本用本地plantuml.jar会图片出现乱码，且无法正确生成html，请使用默认选项（解析为网址）