Markdown To HTML（Java 实现方案）

在 Java 生态中如何将 Markdown 内容高效转换为 HTML？本文梳理主流方案与最佳实践，助你快速集成！

✨ 文章概要

🎯 方案对比
  1. CommonMark + flexmark-java —— 性能优越，支持扩展语法
  2. Pegdown —— 经典方案，社区成熟
  3. Markdown4j —— 轻量级，适合简单场景
🔧 快速集成（flexmark-java）
  1. 添加 Maven 依赖
  2. 创建解析器与渲染器
  3. 自定义扩展（表格、任务列表、锚点等）
🚀 高级特性
  1. 代码语法高亮集成
  2. 自定义 HTML 渲染模板
  3. 安全过滤（XSS 防护）
📖 参考资源
  • flexmark-java 官方文档
  • CommonMark 规范
  • 相关开源项目示例

markdown to html

工程jar依赖

<!–引入Markdown转HTML的插件–> <dependency> <groupId>com.atlassian.commonmark</groupId> <artifactId>commonmark</artifactId> <version>0.17.0</version> </dependency>

<!–扩展 标题–> <dependency> <groupId>com.atlassian.commonmark</groupId> <artifactId>commonmark-ext-heading-anchor</artifactId> <version>0.17.0</version> </dependency>

<!–扩展 表格–> <dependency> <groupId>com.atlassian.commonmark</groupId> <artifactId>commonmark-ext-gfm-tables</artifactId> <version>0.17.0</version> </dependency>

封装工具类

import java.io.IOException; import java.util.Collections; import java.util.List; import java.util.Map; import java.util.Set;

import org.commonmark.Extension; import org.commonmark.ext.gfm.tables.TableBlock; import org.commonmark.ext.gfm.tables.TablesExtension; import org.commonmark.ext.heading.anchor.HeadingAnchorExtension; import org.commonmark.node.Link; import org.commonmark.node.Node; import org.commonmark.parser.Parser; import org.commonmark.renderer.html.AttributeProvider; import org.commonmark.renderer.html.AttributeProviderContext; import org.commonmark.renderer.html.AttributeProviderFactory; import org.commonmark.renderer.html.HtmlRenderer;

/** */ public class MarkdownToHtmlUtils {

/**
 * markdown格式转换成HTML格式
 * @param markdown
 * @return
 */
public static String markdownToHtml(String markdown) {
    Parser parser = Parser.builder().build();
    Node document = parser.parse(markdown);
    HtmlRenderer renderer = HtmlRenderer.builder().build();
    return renderer.render(document);
}

/**
 * 增加扩展[标题锚点，表格生成]
 * Markdown转换成HTML
 * @param markdown
 * @return
 */
public static String markdownToHtmlExtensions(String markdown) {
    //h标题生成id
    Set&lt;Extension&gt; headingAnchorExtensions = Collections.singleton(HeadingAnchorExtension.create());
    //转换table的HTML

// List<Extension> tableExtension = Arrays.asList(TablesExtension.create()); List<Extension> tableExtension = Collections.singletonList(TablesExtension.create()); Parser parser = Parser.builder() .extensions(tableExtension) .build(); Node document = parser.parse(markdown); HtmlRenderer renderer = HtmlRenderer.builder() .extensions(headingAnchorExtensions) .extensions(tableExtension) .attributeProviderFactory(new AttributeProviderFactory() { public AttributeProvider create(AttributeProviderContext context) { return new CustomAttributeProvider(); } }) .build(); return renderer.render(document); }

/**
 * 处理标签的属性
 */
static class CustomAttributeProvider implements AttributeProvider {
    @Override
    public void setAttributes(Node node, String tagName, Map&lt;String, String&gt; attributes) {
        //改变a标签的target属性为_blank
        if (node instanceof Link) {
            attributes.put(&#34;target&#​34;, &#34;_blank&#​34;);
        }
        if (node instanceof TableBlock) {
            attributes.put(&#34;class&#​34;, &#34;ui celled table&#​34;);
        }
    }
}

}

控制层

import com.pay.aide.docs.utils.MarkdownToHtmlUtils; import lombok.extern.slf4j.Slf4j; import org.springframework.core.io.ClassPathResource; import org.springframework.core.io.Resource; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.util.FileCopyUtils; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping;

import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.nio.charset.StandardCharsets;

@Slf4j @Controller @RequestMapping(value = "/portal/docs/&#​34;) public class MarkdownToHtmlController {

/**
*/
@RequestMapping(value = &#34;openapi-framework-{mdName}&#​34;)
public String openapiFramework(HttpServletRequest requests, HttpServletResponse responses, Model model, @PathVariable(&#34;mdName&#​34;) String mdName) throws IOException {
    String markdownToHtml = MarkdownToHtmlUtils.markdownToHtmlExtensions(getJarResource(mdName));
    model.addAttribute(&#34;markdownToHtml&#​34;, markdownToHtml);
    return &#34;/docs/docs_index&#​34;;
}

private String getJarResource(String mdName) throws IOException {
    Resource resource = new ClassPathResource(&#34;openapi/openapi-framework-&#​34; + mdName + &#34;.md&#​34;);
    byte[] binaryData = FileCopyUtils.copyToByteArray(resource.getInputStream());
    String mdData = new String(binaryData, StandardCharsets.UTF_8);
    return mdData;
}

}

页面展示层

<!DOCTYPE html> <html lang="en&#​34;> <head> </head> ${markdownToHtml} <body>

</body>

</html>