markdown转离线单文件html

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,请使用默认选项(解析为网址)

Author: zcp
Reprint policy: All articles in this blog are used except for special statements CC BY 4.0 reprint polocy. If reproduced, please indicate source zcp !
评论
 Previous
迟到的2021年总结——时间都去哪了
1 目前的状态说到最近的状态,从3个多月博客没有更新、个人年终总结拖到2022年过了快$\frac{1}{4}$才想起来写就可以看出来:慵懒、浑浑噩噩、行尸走肉…具体表现在: 近2个月没去健身房、下班后只想打游戏丝毫不想学习、找游
Next 
《死月妖花~四月八日~》游玩思考记录1
1 前言上班之后基本上很少有时间玩这类游戏,之前也偶尔有粗略找过一些,没发现什么好的作品。直到上周翻番組的榜单时,一个叫做《死月妖花 (しがつようか) ~四月八日~》的同人作品映入我的眼中。给我的第一印象是:看起来像是我喜欢的类型
  TOC