Quickstart

What is DocStencil?

DocStencil is a document templating engine for the JVM that lets you generate Word documents (DOCX) from templates. Design your templates as plain DOCX files in Microsoft Word using simple {placeholder} syntax, then render them with your data.

Features:

• Loops & Conditions: Render paragraphs, list items, table rows, or table columns conditionally or in a loop
• Styling: Placeholders preserve the original formatting when replaced
• Function Calling: Call any Java class, function, or data structure from within templates
• Extensible: Module system for inserting hyperlinks, comments, and more

Installation

DocStencil requires JDK 8 or higher.

Maven

<dependencies>
    ...
    <dependency>
        <groupId>com.docstencil</groupId>
        <artifactId>docstencil-core</artifactId>
        <version>0.2.1</version>
    </dependency>
    ...
</dependencies>

Gradle (Kotlin)

dependencies {
    ...
    implementation("com.docstencil:docstencil-core:0.2.1")
    ...
}

Gradle (Groovy)

dependencies {
    ...
    implementation 'com.docstencil:docstencil-core:0.2.1'
    ...
}

Your First Template

Create a new plain DOCX file with placeholders:

Template.docx

{$format(date)}

Dear Mr. {firstName} {generateLastName(firstName)},

...

Then pass your data as a map and render the template:

Kotlin

import com.docstencil.core.api.OfficeTemplate
import java.time.LocalDate

fun main() {
    // Load template
    val template = OfficeTemplate.fromFile("Template.docx")

    // Render with data
    val data = mapOf(
        "date" to LocalDate.now(),
        "firstName" to "Björn",
        "generateLastName" to { firstName: String -> firstName + "son" }
    )
    val result = template.render(data)

    // Save output
    result.writeToFile("Output.docx")
}

Java

import com.docstencil.core.api.OfficeTemplate;
import com.docstencil.core.api.OfficeTemplateResult;
import java.time.LocalDate;
import java.util.Map;
import java.util.function.Function;

public class Main {
    public static void main(String[] args) throws Exception {
        // Load template
        OfficeTemplate template = OfficeTemplate.fromFile("Template.docx");

        // Render with data
        Function<String, String> generateLastName = firstName -> firstName + "son";
        Map<String, Object> data = Map.of(
            "date", LocalDate.now(),
            "firstName", "Björn",
            "generateLastName", generateLastName
        );
        OfficeTemplateResult result = template.render(data);

        // Save output
        result.writeToFile("Output.docx");
    }
}

The output file contains all evaluated expressions in place of the placeholders, preserving the original styles and formatting:

Output.docx

2025/12/17

Dear Mr. Björn Björnson,

...

Any errors encountered during rendering are reported as comments in the output file.

Next Steps

Now that you've generated your first template, learn about accessing data in Java classes, loops, and conditionals in the Basics guide.