1.markdown转html
将 markdown 文档转换为 html,算是很多业务场景里的基础能力,比如博客系统渲染文章、支持 markdown 语法的评论功能等,都在用它
要自己从零实现一个 markdown 语法解析器,工作量可不小;好在开源世界里已经有很多现成的轮子,markdown-plugin 选的是 flexmark(之前看开源博客系统 Solo 源码的时候接触到的包),本篇就来讲一下这个插件在它基础上封装出来的 MarkDown2HtmlWrapper 怎么用
1. 依赖引入
项目已发布到 maven 中央仓库,直接依赖即可
maven 项目在 pom.xml 中添加依赖,建议使用最新版本:
<!-- https://mvnrepository.com/artifact/com.github.liuyueyi.media/markdown-plugin -->
<dependency>
<groupId>com.github.liuyueyi.media</groupId>
<artifactId>markdown-plugin</artifactId>
<version>3.1.0</version>
</dependency>
gradle 项目则在 build.gradle 中添加:
// https://mvnrepository.com/artifact/com.github.liuyueyi.media/markdown-plugin
implementation 'com.github.liuyueyi.media:markdown-plugin:3.1.0'
这个插件内部已经把 flexmark(当前版本 0.62.2)、xhtmlrenderer、nekohtml 这些依赖都打好了,我们只管用就行,不需要再单独引入 flexmark 三件套
2. 设计思路
先想一下我们期望的调用姿势:给我一段 markdown 文本(文件、网络、字符串都行),还我一个 html
所以封装的核心就是两件事:
- 输入源的适配:文件、url、流、纯文本,四种入口统一收口到一个转换方法
- 输出结果不只是 html 字符串,还得带样式:转换出来的裸 html 是没有 css 的,丢到页面上或者渲染成图片都不好看,所以返回值里得把 css 也一起带上
于是就有了返回值 MarkdownEntity,它比一个单纯的 html 字符串多了两样东西:
css:默认加载插件内置的md/huimarkdown.css样式divStyle:html 内容外层包了一个<div>标签,这个 map 里维护的就是这个 div 的属性,可以往里面塞统一的宽高、字体、class 等
最后 toString 的时候,把 css 和带属性的 div 拼在 html 外面:
@Override
public String toString() {
return css + "\n<div " + parseDiv() + ">\n" + html + "\n</div>";
}
3. 使用姿势
3.1 四种输入入口
MarkDown2HtmlWrapper 提供了四个静态方法,覆盖了常见的输入姿势:
// 从本地文件读取(支持相对路径,或 "/" 开头的 classpath 路径)
public static MarkdownEntity ofFile(String path) throws IOException
// 从网络读取 markdown 文件
public static MarkdownEntity ofUrl(String url) throws IOException
// 从输入流读取
public static MarkdownEntity ofStream(InputStream stream) throws IOException
// 直接传 markdown 语义的文本
public static MarkdownEntity ofContent(String content)
最简单的使用,就是从文件中读取 markdown 内容然后转换,三行搞定:
@Test
public void markdown2html() throws IOException {
String file = "md/tutorial.md";
MarkdownEntity html = MarkDown2HtmlWrapper.ofFile(file);
System.out.println(html.toString());
}
如果 markdown 内容本来就在内存里(比如用户提交的评论),直接用 ofContent:
String md = "### 标题\n\n- item1\n- item2\n\n> 一段引用文字";
MarkdownEntity entity = MarkDown2HtmlWrapper.ofContent(md);
// 拿到纯 html 片段
String html = entity.getHtml();
// 拿到完整的带 css 和外层 div 的内容
String full = entity.toString();
注意 ofStream 内部是用 StandardCharsets.UTF_8 读取的,所以只要你的输入源本身是 utf-8 编码,中文不会出问题
3.2 底层的 Flexmark 配置
上面四个入口最终都会走到 parse 方法,这里面就是 flexmark 的标准用法:
/**
* markdown to html
*
* @param content markdown contents
* @return parse html contents
*/
public static String parse(String content) {
MutableDataSet options = new MutableDataSet();
options.setFrom(ParserEmulationProfile.MARKDOWN);
// enable table parse!
options.set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create()));
Parser parser = Parser.builder(options).build();
HtmlRenderer renderer = HtmlRenderer.builder(options).build();
Node document = parser.parse(content);
return renderer.render(document);
}
两个关键配置说一下:
options.setFrom(ParserEmulationProfile.MARKDOWN):解析风格设置为标准 MARKDOWNoptions.set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create())):加载表格扩展插件,没有这个,| a | b |这种表格语法是解析不出来的
默认情况下插件只加载了 tables 这一个扩展,如果还需要其他扩展语法(比如删除线、任务列表、GFM 风格的自动链接等),可以自己仿照 parse 方法,往 Parser.EXTENSIONS 里追加对应的扩展,flexmark 官方提供了 flexmark-ext-gfm-strikethrough、flexmark-ext-gfm-tasklist 等一堆扩展包,按需引入即可
3.3 换一套 css 主题
默认的 MD_CSS 是插件启动时从内置资源 md/huimarkdown.css 读取的,长在 MarkDown2HtmlWrapper 的一个静态变量上:
public static String MD_CSS = null;
static {
MD_CSS = buildCssContent("md/huimarkdown.css");
}
如果你不喜欢这个默认样式,插件里还内置了几套主题 css(在插件的 resources 目录下):heyrain.css、hyper.css、koala.css、huimarkdown_code.css,可以用 buildCssContent 自己换:
MarkdownEntity entity = MarkDown2HtmlWrapper.ofFile("md/tutorial.md");
// 用 heyrain 主题替换默认的 huimarkdown 样式
entity.setCss(MarkDown2HtmlWrapper.buildCssContent("md/heyrain.css"));
buildCssContent 做的事情就是读文件然后包一层 <style type="text/css"> 标签;你也可以传一个自己写的 css 文件路径进去,一样的效果
3.4 MarkdownEntity 的其他玩法
MarkdownEntity 上还有两个值得了解的方法:
addDivStyle:往最外层的 div 上追加属性。默认情况下,ofContent 会给 div 加一个 class="markdown-body ",好让内置 css 里的 .markdown-body 选择器能生效:
// 默认行为
entity.addDivStyle("class", "markdown-body ");
// 也可以自己再追加别的,比如:
entity.addDivStyle("style", "width:600px;");
addWidthCss:给指定标签批量加宽度限制的 css,内部模板长这样:
public static String TAG_WIDTH = "<style type=\"text/css\"> %s { width:85%%} </style>";
比如 entity.addWidthCss("img") 就是让 html 里所有的图片最大宽度为 85%,防止大图撑破容器。这个方法在转图片的链路里会被自动调用,后面讲 markdown 转图片的时候会再提到
4. 常见坑
4.1 表格没有渲染出来
自己单独用 flexmark 的时候,最容易踩的就是这个坑:表格语法原样输出成文本,并没有变成 <table>。原因就是默认的 Parser 没加载表格扩展,必须显式加 TablesExtension.create()。用 markdown-plugin 的话这一点已经处理好了,不用担心
4.2 直接 getHtml() 没有样式
getHtml() 拿到的只是 markdown 解析后的裸 html 片段,css 在 entity.getCss() 里。如果想得到一个能直接在浏览器里打开显示样式的完整内容,要用 entity.toString(),它会把 css + 带属性的 div + html 一起拼出来
4.3 ofUrl 的地址格式
ofUrl 底层还是走的 FileReadUtil.getStreamByFileName(url),传的是 http 开头的完整 url 就能正常拉取;但要注意目标文件得是公网可访问的,而且这个方法没有复杂的鉴权、重定向处理,特殊场景建议自己先下载成流再用 ofStream
5. 小结
本篇介绍了 markdown 转 html 的基本使用,四种输入入口 + 默认样式 + 自定义主题;不过光转成 html 只算完成了一半,很多场景下(比如图文消息推送)我们最终要的是一张图片,这就得靠下一篇的 Html2ImageWrapper 登场了
项目地址:
- https://github.com/liuyueyi/quick-media
QuickMedia目标是创建一个专注图文,音视频,二维码处理的开源项目