easydoc

English | 简体中文

A Word (.docx) generation component built on docx4j and a variety of template engines. Render WordprocessingML documents from templates (Freemarker, Velocity, Thymeleaf, Beetl, Rythm, Jetbrick, HTTL, Webit, JSP) or directly from XHTML.

Table of Contents

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage / API
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

1. Project Overview

easydoc (project description: Building doc documents based on xhtml templates using docx4j) is a multi-module component for fast Word document output. A core module defines the WordprocessingMLTemplate contract (template + variables -> WordprocessingMLPackage), while separate modules adapt each template engine and an XHTML import path.

What it is	What it is not
Template-driven .docx generation (docx4j)	A PDF renderer (see the sibling project easypdf)
Pluggable template engines (Freemarker, Velocity, Thymeleaf, Beetl, Rythm, Jetbrick, HTTL, Webit, JSP, XHTML)	A document editor or viewer
Direct XHTML -> WordprocessingML conversion	A cloud document service

Typical use cases:

Use case	Module
Fill a Word template with a variable map	easydoc-core (WordprocessingMLDocxTemplate)
Render templates with your favorite engine	easydoc-freemarker / -velocity / -thymeleaf / -beetl / -rythm / -jetbrick / -httl / -webit / -jsp
Convert XHTML (or a URL / document) to a WordprocessingML package	easydoc-xhtml
Manage shared dependency versions	easydoc-bom

Project status: stable.

2. Features & Status

Feature	Status	Notes
WordprocessingMLTemplate contract	Available	process(File/InputStream, Map<String,Object>) -> WordprocessingMLPackage
WordprocessingMLDocxTemplate	Available	Loads a .docx template via Docx4J.load, creates a dummy document when no template is given
Freemarker engine	Available	WordprocessingMLFreemarkerTemplate (also process(String, Map) overload)
Velocity / Thymeleaf / Beetl / Rythm / Jetbrick / HTTL / Webit / JSP engines	Available	One module per engine, WordprocessingML{Engine}Template
XHTML import	Available	WordprocessingMLHtmlTemplate (File / InputStream / Document / URL) + XHTMLImporterUtils
WML utilities	Available	WML element / paragraph / border utilities, variable clearing, zip helpers, font mapping (ChineseFont, FontMapperHolder)
Output pipeline	Available	WordprocessingMLPackageRender / -Writer / -Extractor
Build events / error handling	Available	bus.event (build start/finish) and bus.error.Slf4jLogger
CI pipeline	Not configured	No CI workflow files in the repository

3. Requirements & Compatibility

Requirement	Version
JDK	8
Maven	3.0+
docx4j	docx4j-core + JAXB variants (Internal / MOXy / ReferenceImpl)
OGNL	Expression support in the core module
Engine modules	Freemarker, Velocity, Thymeleaf, Beetl, Rythm, Jetbrick, HTTL, Webit, JSP (per-module)

Version lines

Branch	JDK	Version pattern
feature/1.0.x	JDK 8	1.0.x.*
feature/2.0.x	JDK 17	2.0.x.*
feature/3.0.x	JDK 21	3.0.x.*

4. Architecture & Modules

  Template sources                       easydoc modules                 output
  ----------------                       --------------                 ------
  .docx template    ->  easydoc-core  (WordprocessingMLTemplate)
  .ftl / .vm / .tpl ->  easydoc-{freemarker,velocity,beetl,thymeleaf,
                         rythm,jetbrick,httl,webit,jsp}
  .html / .xhtml    ->  easydoc-xhtml (WordprocessingMLHtmlTemplate +
                         XHTMLImporterUtils)
                                |
                                v
                     WordprocessingMLPackage (docx4j)
                                |
                                v
                         render / write / extract (easydoc-core io.*)
                                |
                                v
                             output .docx

Module	Responsibility
easydoc-core	Template contract, docx4j/WML utilities, render/write/extract pipeline
easydoc-xhtml	XHTML/HTML -> WordprocessingMLPackage (docx4j ImportXHTML based)
easydoc-freemarker / easydoc-velocity / easydoc-thymeleaf / easydoc-beetl / easydoc-rythm / easydoc-jetbrick / easydoc-httl / easydoc-webit / easydoc-jsp	One adapter per template engine
easydoc-bom	Dependency management BOM

5. Installation

Maven

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>easydoc-core</artifactId>
    <version>1.0.x.20260630-SNAPSHOT</version>
</dependency>

Add the engine module(s) you need, e.g.:

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>easydoc-freemarker</artifactId>
    <version>1.0.x.20260630-SNAPSHOT</version>
</dependency>

Gradle

implementation 'io.github.easy4j:easydoc-core:1.0.x.20260630-SNAPSHOT'
implementation 'io.github.easy4j:easydoc-freemarker:1.0.x.20260630-SNAPSHOT'

Availability: the artifacts are published to the Aliyun private Maven repository and distributed through GitHub Releases; they have not yet been published to Maven Central.

6. Quick Start

Fill a .docx template with a variable map:

import io.github.easy4j.doc.WordprocessingMLDocxTemplate;
import io.github.easy4j.doc.WordprocessingMLTemplate;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

import java.io.File;
import java.util.HashMap;
import java.util.Map;

WordprocessingMLTemplate template = new WordprocessingMLDocxTemplate();

Map<String, Object> variables = new HashMap<>();
variables.put("title", "Meeting Minutes");
variables.put("author", "Alice");

WordprocessingMLPackage doc = template.process(new File("template.docx"), variables);
doc.save(new File("output.docx"));

Expected result: output.docx contains the rendered document. When no template file is passed, a dummy sample document is created (via SampleDocument).

7. Configuration

The core library is template-driven and requires no configuration file. Engine adapters may accept engine-specific settings programmatically:

• WordprocessingMLFreemarkerTemplate.setFreemarkerSettings(Properties) — FreeMarker settings
• WordprocessingMLBeetlTemplate / WordprocessingMLFreemarkerTemplate constructors support landscape / altChunk flags and an XHTML-based variant (WordprocessingMLHtmlTemplate based)

8. Core Usage / API

8.1 Template contract

public interface WordprocessingMLTemplate {
    default WordprocessingMLPackage process(File template, Map<String, Object> variables) throws Exception;
    default WordprocessingMLPackage process(InputStream template, Map<String, Object> variables) throws Exception;
    default WordprocessingMLPackage process(String template, Map<String, Object> variables) throws Exception;
    ...
}

8.2 Freemarker template

WordprocessingMLFreemarkerTemplate tpl = new WordprocessingMLFreemarkerTemplate();
WordprocessingMLPackage doc = tpl.process(new File("report.ftl"), variables);

8.3 XHTML to Word

WordprocessingMLHtmlTemplate html = new WordprocessingMLHtmlTemplate();
WordprocessingMLPackage doc = html.process(new File("page.html"));

8.4 Core packages

Package	Contents
io.github.easy4j.doc	WordprocessingMLTemplate, WordprocessingMLDocxTemplate, Docx4jConstants, SampleDocument, docx4j SAX/StAX template variants
io.github.easy4j.doc.io	WordprocessingMLPackageRender / -Writer / -Extractor / WordprocessingMLTemplateWriter
io.github.easy4j.doc.handler	Output-conversion and variable-replacement handlers
io.github.easy4j.doc.utils	docx4j / WML / zip / font / paragraph / border utilities
io.github.easy4j.doc.wml	WML element rendering and WMLType
io.github.easy4j.doc.fonts	ChineseFont, FontMapperHolder
io.github.easy4j.doc.bus	Build events and error logging

9. Testing & Build

./mvnw clean verify        # build all modules, run tests, generate coverage report
./mvnw clean install       # install all modules into the local repository

• Tests exist in easydoc-core (docx4j demo-style tests), easydoc-velocity and easydoc-xhtml (HTML conversion demos).
• Coverage is measured with the JaCoCo Maven plugin (target: 90% line coverage, haltOnFailure=false).
• The release profile assembles GPG signing + sources + Javadoc + deployment (./mvnw -Prelease clean deploy).

10. Versioning & Branches

Three parallel version lines are maintained:

Branch	JDK	Version pattern
feature/1.0.x	JDK 8	1.0.x.*
feature/2.0.x	JDK 17	2.0.x.*
feature/3.0.x	JDK 21	3.0.x.*

Maintenance strategy: the 1.0.x line receives bug fixes while JDK 8 remains the baseline; feature development primarily targets the 2.0.x / 3.0.x lines.

11. Contributing & License

Contributions are welcome — open an issue or submit a pull request against the matching version-line branch (feature/1.0.x for JDK 8 changes).

This project is licensed under the Apache License, Version 2.0. See the LICENSE file in the repository root for details.