feat(markdown): sync Markdown<->docx from 3.0.x (JDK 17 adaptation)

- flexmark 0.64.8 (Java 11+, OK on JDK 17)
- MarkdownConverter + EasyMarkdown copied from 3.0.x; docx4j 11.5.14
  HTMLSettings/Docx4J.toHTML compatible; test-time physical font
  discovery disabled (docx4j 11.5.14 IdentityPlusMapper assertion on JDK 17)
- Tests: MarkdownConverterTest 4 + EasyMarkdownTest 3
Full verify (JDK 17): BUILD SUCCESS, xhtml 39 tests.

Author: loong10k

easydoc-xhtml/pom.xml

@@ -47,6 +47,12 @@
 		    <artifactId>docx4j-ImportXHTML-core</artifactId>
 		</dependency>
 
+		<!-- flexmark：Markdown → HTML（GFM 表格/代码块扩展） -->
+		<dependency>
+		    <groupId>com.vladsch.flexmark</groupId>
+		    <artifactId>flexmark-all</artifactId>
+		</dependency>
+
 		<!-- ======== Test ======== -->
 
 		<!-- eclipselink：JPA 实现，测试环境用于 docx4j MOXy JAXB 兼容验证 -->

easydoc-xhtml/src/main/java/io/github/easy4j/doc/xhtml/markdown/EasyMarkdown.java

@@ -0,0 +1,51 @@
+package io.github.easy4j.doc.xhtml.markdown;
+
+import java.io.ByteArrayOutputStream;
+import java.util.Map;
+
+import org.docx4j.Docx4J;
+import org.docx4j.convert.out.HTMLSettings;
+import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+
+import io.github.easy4j.doc.xhtml.WordprocessingMLHtmlTemplate;
+
+/**
+ * Markdown ↔ docx 转换门面（对齐 EasyDocx 风格）。MD→docx 走
+ * MarkdownConverter.mdToHtml + 现有 WordprocessingMLHtmlTemplate（HTML→docx）；
+ * 薄封装，不替代引擎。
+ */
+public final class EasyMarkdown {
+
+	private EasyMarkdown() {
+	}
+
+	/** Markdown → docx（无变量替换）。 */
+	public static WordprocessingMLPackage markdownToDocx(String markdown) throws Exception {
+		return markdownToDocx(markdown, null);
+	}
+
+	/** Markdown → docx。variables 参数当前未生效（WordprocessingMLHtmlTemplate 暂不支持 HTML 变量替换）；传入 null 即可。 */
+	public static WordprocessingMLPackage markdownToDocx(String markdown,
+			Map<String, Object> vars) throws Exception {
+		String html = MarkdownConverter.mdToHtml(markdown);
+		WordprocessingMLHtmlTemplate template = new WordprocessingMLHtmlTemplate();
+		return template.process(html, vars);
+	}
+
+	/** docx → Markdown（经 docx4j HTML 导出 + 简化 HTML→MD 映射）。null 输入返回空串。 */
+	public static String docxToMarkdown(WordprocessingMLPackage pkg) throws Exception {
+		if (pkg == null) {
+			return "";
+		}
+		// 无现成的 writeToHtml(pkg, OutputStream) 封装可用，
+		// 故直接使用 docx4j API（HTMLSettings + Docx4J.toHTML）导出到内存流。
+		HTMLSettings htmlSettings = Docx4J.createHTMLSettings();
+		htmlSettings.setWmlPackage(pkg);
+		// 防止含图片文档在 HTML 导出时因未设置 imageDirPath 而失败
+		htmlSettings.setImageDirPath(System.getProperty("java.io.tmpdir"));
+		htmlSettings.setImageTargetUri("images");
+		ByteArrayOutputStream out = new ByteArrayOutputStream();
+		Docx4J.toHTML(htmlSettings, out, Docx4J.FLAG_EXPORT_PREFER_XSL);
+		return MarkdownConverter.htmlToMarkdown(out.toString("UTF-8"));
+	}
+}

easydoc-xhtml/src/main/java/io/github/easy4j/doc/xhtml/markdown/MarkdownConverter.java

@@ -0,0 +1,63 @@
+package io.github.easy4j.doc.xhtml.markdown;
+
+import com.vladsch.flexmark.html.HtmlRenderer;
+import com.vladsch.flexmark.parser.Parser;
+import com.vladsch.flexmark.util.ast.Node;
+import com.vladsch.flexmark.util.data.MutableDataSet;
+
+/**
+ * Markdown 文本 → HTML 字符串转换（flexmark 驱动，启用 GFM 表格/删除线扩展）。
+ * 输出 HTML 供 easydoc 现有 HTML→docx 管线消费。
+ */
+public final class MarkdownConverter {
+
+	private static final Parser PARSER;
+	private static final HtmlRenderer RENDERER;
+
+	static {
+		MutableDataSet options = new MutableDataSet();
+		options.set(Parser.EXTENSIONS, java.util.Arrays.asList(
+				com.vladsch.flexmark.ext.tables.TablesExtension.create(),
+				com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughExtension.create(),
+				com.vladsch.flexmark.ext.autolink.AutolinkExtension.create()));
+		PARSER = Parser.builder(options).build();
+		RENDERER = HtmlRenderer.builder(options).build();
+	}
+
+	private MarkdownConverter() {
+	}
+
+	/** Markdown → HTML。null 输入返回空串。 */
+	public static String mdToHtml(String markdown) {
+		if (markdown == null) {
+			return "";
+		}
+		Node document = PARSER.parse(markdown);
+		return RENDERER.render(document);
+	}
+
+	/** HTML → Markdown（简化映射：标题/段落/粗斜体/列表/表格/代码块）。 */
+	public static String htmlToMarkdown(String html) {
+		if (html == null) {
+			return "";
+		}
+		String out = html
+				.replaceAll("(?i)<h1[^>]*>", "\n# ")
+				.replaceAll("(?i)</h1>", "\n")
+				.replaceAll("(?i)<h2[^>]*>", "\n## ")
+				.replaceAll("(?i)</h2>", "\n")
+				.replaceAll("(?i)<h3[^>]*>", "\n### ")
+				.replaceAll("(?i)</h3>", "\n")
+				.replaceAll("(?i)<strong[^>]*>", "**").replaceAll("(?i)</strong>", "**")
+				.replaceAll("(?i)<em[^>]*>", "*").replaceAll("(?i)</em>", "*")
+				.replaceAll("(?i)<li[^>]*>", "- ").replaceAll("(?i)</li>", "\n")
+				.replaceAll("(?i)<p[^>]*>", "\n").replaceAll("(?i)</p>", "\n")
+				.replaceAll("(?i)<td[^>]*>", " | ").replaceAll("(?i)</td>", "")
+				.replaceAll("(?i)</tr>", "\n")
+				.replaceAll("(?i)<pre[^>]*>", "\n```\n").replaceAll("(?i)</pre>", "\n```\n")
+				.replaceAll("(?i)</?table[^>]*>", "\n")
+				.replaceAll("(?i)</?thead[^>]*>|</?tbody[^>]*>|</?tr[^>]*>", "\n")
+				.replaceAll("(?i)<[^>]+>", ""); // 残余标签
+		return out.replaceAll("\\n{3,}", "\n\n").trim();
+	}
+}

easydoc-xhtml/src/test/java/io/github/easy4j/doc/xhtml/markdown/EasyMarkdownTest.java

@@ -0,0 +1,34 @@
+package io.github.easy4j.doc.xhtml.markdown;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+import org.junit.jupiter.api.Test;
+
+class EasyMarkdownTest {
+
+	@Test
+	void markdownToDocxProducesPackage() throws Exception {
+		WordprocessingMLPackage pkg = EasyMarkdown.markdownToDocx(
+				"# 标题\n\n这是 **加粗** 内容。\n\n- 列表一\n- 列表二");
+		assertNotNull(pkg);
+		String xml = pkg.getMainDocumentPart().getXML();
+		assertTrue(xml.contains("标题"), "heading text must appear in the docx");
+		assertTrue(xml.contains("加粗"), "bold text must appear in the docx");
+	}
+
+	@Test
+	void markdownToDocxHandlesNullAndEmpty() throws Exception {
+		assertNotNull(EasyMarkdown.markdownToDocx(null), "null markdown yields a package");
+		assertNotNull(EasyMarkdown.markdownToDocx(""), "empty markdown yields a package");
+	}
+
+	@Test
+	void docxToMarkdownConvertsHeadingAndBold() throws Exception {
+		WordprocessingMLPackage pkg = EasyMarkdown.markdownToDocx("# 标题\n\n**加粗** 内容");
+		String md = EasyMarkdown.docxToMarkdown(pkg);
+		assertTrue(md.contains("标题"), "heading text must appear in markdown output");
+		assertTrue(md.contains("加粗"), "text must appear in markdown output");
+	}
+}

easydoc-xhtml/src/test/java/io/github/easy4j/doc/xhtml/markdown/MarkdownConverterTest.java

@@ -0,0 +1,38 @@
+package io.github.easy4j.doc.xhtml.markdown;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+class MarkdownConverterTest {
+
+	@Test
+	void mdToHtmlConvertsHeadingsAndParagraphs() {
+		String html = MarkdownConverter.mdToHtml("# Title\n\nHello **world**.");
+		assertTrue(html.contains("<h1>"), "heading must render to <h1>");
+		assertTrue(html.contains("<strong>world</strong>"), "bold must render to <strong>");
+		assertTrue(html.contains("<p>"), "paragraph must render to <p>");
+	}
+
+	@Test
+	void mdToHtmlConvertsTable() {
+		String html = MarkdownConverter.mdToHtml("| A | B |\n|---|---|\n| 1 | 2 |");
+		assertTrue(html.contains("<table>"), "GFM table must render to <table>");
+		assertTrue(html.contains("<td>1</td>"), "table cell must render");
+	}
+
+	@Test
+	void mdToHtmlConvertsCodeBlockAndList() {
+		String html = MarkdownConverter.mdToHtml("```java\nint x=1;\n```\n\n- item1\n- item2");
+		assertTrue(html.contains("<pre>"), "code block must render to <pre>");
+		assertTrue(html.contains("<li>item1</li>"), "list item must render");
+	}
+
+	@Test
+	void htmlToMarkdownHandlesTagsWithAttributes() {
+		String md = MarkdownConverter.htmlToMarkdown(
+				"<strong class=\"x\">bold</strong> and <li class=\"y\">item</li>");
+		assertTrue(md.contains("**bold**"), "strong with attribute must become **bold**");
+		assertTrue(md.contains("- item"), "li with attribute must become list item");
+	}
+}

easydoc-xhtml/src/test/resources/docx4j.properties

@@ -37,6 +37,12 @@ docx4j.javax.xml.parsers.DocumentBuilderFactory.donotset = false
 #docx4j.fonts.fop.util.FopConfigUtil.substitutions = 
 #docx4j.fonts.microsoft.MicrosoftFonts = org/docx4j/fonts/microsoft/MicrosoftFonts.xml
 
+# 禁用物理字体自动发现：docx4j 11.5.14 解析部分 macOS 系统字体的 GPOS 表时，
+# GlyphPositioningTable$DeviceTable 的 assert 会在启用断言的测试 JVM 中抛出
+# AssertionError（EasyMarkdown.docxToMarkdown 的 Docx4J.toHTML 路径触发）；
+# HTML 导出与 MD 转换不依赖物理字体发现，生产环境（默认不开 -ea）不受影响。
+docx4j.fonts.discoverPhysicalFonts.enabled = false
+
 
 docx4j.model.datastorage.placeholder = OpenDoPE/placeholder.xml
 docx4j.model.datastorage.OpenDoPEReverter.Supported = true

pom.xml

@@ -79,6 +79,8 @@
         <commons-io.version>2.22.0</commons-io.version>
         <commons-lang3.version>3.20.0</commons-lang3.version>
         <commons-logging.version>1.3.5</commons-logging.version>
+        <!-- Markdown 解析（MD→HTML 渲染，Java 8 兼容） -->
+        <flexmark.version>0.64.8</flexmark.version>
         <jackson-bom.version>2.22.1</jackson-bom.version>
         <javax.mail-api.version>1.6.2</javax.mail-api.version>
         <jsoup.version>1.16.1</jsoup.version>
@@ -746,6 +748,17 @@
                 <artifactId>jsoup</artifactId>
                 <version>${jsoup.version}</version>
             </dependency>
+
+            <!-- ======== Markdown 解析 ======== -->
+
+            <!-- https://mvnrepository.com/artifact/com.vladsch.flexmark/flexmark-all -->
+            <!-- flexmark 聚合构件（Markdown → HTML，含 GFM 表格/删除线/自动链接扩展，easydoc-xhtml 使用） -->
+            <dependency>
+                <groupId>com.vladsch.flexmark</groupId>
+                <artifactId>flexmark-all</artifactId>
+                <version>${flexmark.version}</version>
+            </dependency>
+
             <!-- ======== Docx4j 全家桶（11.5.14） ======== -->
 
             <!-- https://mvnrepository.com/artifact/org.docx4j/docx4j-core -->