1.markdown转html

一灰灰blogQuickMediamarkdown-plugin约 1716 字大约 6 分钟

将 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):解析风格设置为标准 MARKDOWN
  • options.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 登场了

项目地址:

Loading...