Word Document Template Engine for Java & Kotlin
Generate DOCX files with mail merge, loops, and conditionals

Documentation • Examples • Report Bug

DocStencil is an open-source document generation library for Java and Kotlin. It works like mail merge for Word documents: Design your templates in Microsoft Word using familiar {placeholder} syntax, then render them with your data to produce professional DOCX files.

Use cases:

• Invoices & Receipts: Generate billing documents with line items, totals, and customer details
• Contracts & Agreements: Create legal documents with dynamic clauses and signatures
• Reports: Build data-driven reports with tables, charts, and formatted numbers

Templates can be edited by anyone familiar with Word. For most use cases no programming knowledge is required. Your team can update document layouts, styles, and content without touching code.

DocStencil focuses on simplicity: you design templates in Word, not in code. Compare the "Hello World" example above to docx4j or Apache POI: DocStencil requires no XML manipulation. Word is your visual editor, where you define styles and formatting.

• Placeholder replacement: Use simple placeholders: {name}
• Loops & Conditionals: Generate dynamic tables and show/hide sections with {for} and {if}
• Nested Data: Access complex data structures with dot notation and function calling: {customer.address.city}, {customerService.get(invoice.getCustomerId()).getName()}
• Formatting: Format dates and numbers with built-in functions: {$format(date, "MMMM dd, yyyy")}
• Preserves Styles: Your Word styles, fonts, and layouts stay intact
• Parallel Evaluation: Template expressions can be evaluated in parallel; ideal for large templates that fetch data lazily

• JDK 8 or higher

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

implementation("com.docstencil:docstencil-core:0.2.1")

implementation 'com.docstencil:docstencil-core:0.2.1'

1. Create a Word template:

{if name == "world"}
Hello {name}!
{end}

2. Render with your data:

import com.docstencil.core.api.OfficeTemplate

fun main() {
    val template = OfficeTemplate.fromFile("template.docx")
    val result = template.render(mapOf("name" to "world"))
    result.writeToFile("Output.docx")
}

import com.docstencil.core.api.OfficeTemplate;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        var template = OfficeTemplate.fromFile("template.docx");
        var result = template.render(Map.of("name", "world"));
        result.writeToFile("Output.docx");
    }
}

3. Result:

Hello World!

Access nested properties in maps, POJOs with getters, records, and data classes with dot notation:

Ship to: {customer.address.street}, {customer.address.city}

Repeat content for each item in a list or table row:

{for item in items}
- {item.name}: ${item.price}
{end}

Show content based on conditions:

{if invoice.subtotal >= 100 and !user.registered}
Use code COUPON10 to get 10% off your next order!
{end}

DocStencil has a rich and expressive templating language that supports:

• Formatting of dates and numbers
• Pipe notation with lambdas
• Inserting raw XML
• Inserting hyperlinks
• and much more ...

The examples/ directory contains complete, runnable projects:

• spring-boot-getting-started (Java, Kotlin): Minimal Spring Boot app that generates a DOCX from a template
• spring-boot-invoice-generator (Java, Kotlin): Invoice generation with line items, totals, and formatting

For comprehensive guides and API reference, visit the Documentation.

• Quickstart Guide
• Template Basics
• Built-in Functions
• Pro Features

This project is dual-licensed under the Apache License 2.0 and MIT License. See LICENSE for details.