flexmark-java HTML 转 Markdown 详细说明

flexmark-java 是基于 CommonMark 规范的 Java 解析库，提供了灵活的 HTML 转 Markdown 转换能力，支持自定义扩展和精细化配置，以下从核心能力、使用方式、配置项、扩展支持、常见问题与修复等维度整理详细说明。

一、核心模块与基础能力

1. 核心模块

flexmark-java 中负责 HTML 转 Markdown 的核心模块为 flexmark-html2md-converter，该模块在 0.50.18 版本 正式新增，同时废弃了旧的 flexmark-html-parser 相关类，是当前推荐使用的 HTML 转 Markdown 实现。

2. 原生支持的转换特性

该模块支持将主流 HTML 标签/格式转换为标准 Markdown，原生支持的转换类型包括：

• 基础文本样式：粗体（bold）、斜体（italic）、行内代码（inline code）、删除线（strike through）、下标（subscript）、上标（superscript）
• 块级元素：块引用（block quotes）、无序列表/有序列表（bullet/numbered lists）、定义列表（definition）、围栏代码块（fenced code）
• 表格（tables）、缩写（abbreviations）、侧边栏（aside）
• 多媒体：多行 URL 图片（multi-line URL images）

二、基础使用示例

1. 核心依赖（Maven/Gradle）

需引入 flexmark-html2md-converter 模块（需匹配对应版本，如 0.50.18+）：

<!-- Maven 依赖示例 -->
<dependency>
    <groupId>com.vladsch.flexmark</groupId>
    <artifactId>flexmark-html2md-converter</artifactId>
    <version>0.50.18</version> <!-- 推荐使用稳定版本，如 0.64.8 -->
</dependency>
<!-- 核心库依赖（必选） -->
<dependency>
    <groupId>com.vladsch.flexmark</groupId>
    <artifactId>flexmark-core</artifactId>
    <version>0.64.8</version>
</dependency>

2. 基础转换代码

flexmark-java 提供了可扩展的转换 API，基础流程如下（参考官方示例 HtmlToMarkdownCustomizedSample.java）：

import com.vladsch.flexmark.html2md.converter.FlexmarkHtmlParser;
import com.vladsch.flexmark.html2md.converter.HtmlConverter;
import com.vladsch.flexmark.util.data.MutableDataSet;

public class HtmlToMarkdownDemo {
    public static void main(String[] args) {
        // 1. 配置转换选项
        MutableDataSet options = new MutableDataSet();
        
        // 可选：自定义转换规则（如禁用表格标题、覆盖字符替换映射等）
        // options.set(FlexmarkHtmlParser.TABLE_CAPTION, false); // 禁用表格标题转换
        
        // 2. 构建 HTML 解析器和转换器
        FlexmarkHtmlParser htmlParser = FlexmarkHtmlParser.builder(options).build();
        HtmlConverter converter = HtmlConverter.builder(options).build();
        
        // 3. 待转换的 HTML 内容
        String htmlContent = "<p>This is <strong>bold</strong> and <em>italic</em> text.</p>"
                + "<ul><li>List item 1</li><li>List item 2</li></ul>";
        
        // 4. 执行转换
        String markdown = converter.convert(htmlParser.parse(htmlContent));
        
        // 输出结果：This is **bold** and *italic* text.\n\n- List item 1\n- List item 2
        System.out.println(markdown);
    }
}

三、关键配置项与自定义扩展

1. 核心配置项（FlexmarkHtmlParser）

flexmark-java 提供了精细化的配置项，支持覆盖默认转换行为，核心配置包括：

2. 自定义标签处理

支持通过扩展 API 覆盖默认标签处理逻辑（修复 #313 需求），例如自定义 <a> 标签、嵌套列表的转换规则：

// 自定义标签处理器示例（简化版）
FlexmarkHtmlParser htmlParser = FlexmarkHtmlParser.builder(options)
        .customTagProcessor((tagName, attributes, content) -> {
            if ("a".equals(tagName)) {
                // 自定义链接转换规则：[content](href)
                String href = attributes.get("href");
                return "[" + content + "](" + href + ")";
            }
            return null; // 返回 null 则使用默认处理
        })
        .build();

3. 字符替换映射自定义

通过 TYPOGRAPHIC_REPLACEMENT_MAP 覆盖内置字符转换规则，例如自定义中文标点转换：

Map<String, String> replacementMap = new HashMap<>();
replacementMap.put("&nbsp;", " "); // 替换非断行空格为普通空格
replacementMap.put("&copy;", "©"); // 保留版权符号不转换
options.set(FlexmarkHtmlParser.TYPOGRAPHIC_REPLACEMENT_MAP, replacementMap);

四、版本修复与常见问题

1. 核心问题修复（HTML 转 Markdown 相关）

flexmark-java 在多个版本中修复了 HTML 转 Markdown 的关键问题，需关注版本兼容性：

2. 兼容性注意事项

• Java 版本：0.50.16 版本起，flexmark-java 最低要求 Java 8，编译基于 JDK 8；
• 迁移指南：从 0.42.x 升级到 0.50.x 可参考官方迁移文件 migrate flexmark-java 0_42_x to 0_50_0.xml；
• 嵌套列表缩进：支持配置子列表所需的空格数（修复 #382 需求），避免嵌套列表转换异常。

五、最佳实践

1. 版本选择：优先使用 0.50.18+ 版本，该版本完善了 html2md-converter 模块，修复了大量转换问题；
2. 测试覆盖：针对自定义标签、嵌套列表、表格等复杂场景，参考官方示例 HtmlToMarkdownCustomizedSample.java 编写测试；
3. 特殊场景处理：
   • 处理 base64 图片：0.40.0 版本新增 base64 图片支持（#397），可正常转换含 base64 编码的 <img> 标签；
   • 预格式化文本：0.42.14 版本修复了 <pre> 内 <code> 标签的转换问题（#326），避免多 <code> 标签错误解析；
   • 邮件链接：0.42.14 版本修复了 Docx 转换器中邮件链接的转换逻辑，同时 0.59.114 版本优化了自动链接/邮件链接的 <> 包裹问题。

六、参考资源

1. 官方仓库：https://github.com/vsch/flexmark-java
2. 官方示例：HtmlToMarkdownCustomizedSample.java
3. 版本变更记录：https://github.com/vsch/flexmark-java/blob/master/VERSION.md
4. 第三方文档：https://daichangya.github.io/flexmark-java-doc/#/./Home、https://tio-boot.litongjava.com/zh/34_spider/06.html