miku-docx2md-java

miku-docx2md-java is the Java straight-conversion runtime and CLI for miku-docx2md.

The tool converts local .docx files to Markdown. The Java version keeps the Node.js / TypeScript upstream vocabulary and observable CLI behavior traceable, while packaging the converter as a Maven-built executable jar.

Usage

Build:

mvn test
mvn package

Run:

java -jar target/miku-docx2md-1.2.1.jar ./sample.docx --out ./sample.md

Summary output:

java -jar target/miku-docx2md-1.2.1.jar ./sample.docx --out ./sample.md --summary --summary-out ./sample.summary.txt

Image assets:

java -jar target/miku-docx2md-1.2.1.jar ./sample.docx --out ./sample.md --assets-dir ./sample.assets

Debug comments:

java -jar target/miku-docx2md-1.2.1.jar ./sample.docx --out ./sample.md --debug

Omit YAML front matter:

java -jar target/miku-docx2md-1.2.1.jar ./sample.docx --out ./sample.md --front-matter exclude

Batch directory conversion:

java -jar target/miku-docx2md-1.2.1.jar \
  --input-directory ./docx \
  --output-directory ./markdown \
  --recursive

Current Scope

• Java source / target compatibility: 1.8
• Build tool: Maven
• Test framework: JUnit Jupiter
• Primary verification: mvn test
• Runtime package: executable fat jar under target/
• Distribution package: target/miku-docx2md-1.2.1-dist.zip

The Java port covers the runtime core, CLI path, document XML, relationships, styles, numbering, Word comments as Markdown footnotes, tracked insertion / deletion markup, Markdown rendering, YAML front matter, image asset extraction, summary text, file output, and Java-side batch conversion. Browser UI behavior from upstream is out of scope for this Java repository.

Maven plugin support is separated into miku-docx2md-java-maven. That repository owns jp.igapyon:miku-docx2md-maven-plugin and its Maven goal documentation, examples, and smoke tests.

GitHub Release asset workflow support is provided by .github/workflows/release-cli-runtime.yml. It builds from v* tags or manual tag_name dispatch and uploads the runtime jar plus sources jar.

Upstream And Sister Reference

• Upstream Node.js / TypeScript repository: https://github.com/igapyon/miku-docx2md
• Local upstream checkout used for this conversion: ../miku-docx2md
• Upstream snapshot checked locally: branch devel-tiga0702vfd, tag v1.2.1, commit f5bdf21
• Sister Java project: https://github.com/igapyon/miku-xlsx2md-java
• Local sister checkout used as the Java shape reference: ../miku-xlsx2md-java
• Closest local sister checkout used for historical Maven plugin and batch CLI shape: workplace/miku-xlsx2md-java-devel

See docs/ for upstream class, CLI, and test mapping.

Repository Operation

workplace/ is a local scratch area for upstream clones, generated comparison outputs, extracted archives, and temporary verification artifacts. Only workplace/.gitkeep is tracked.

.mvn/jvm.config is tracked for repository-local Maven JVM settings.

License

Apache License 2.0. See LICENSE.