README.md

docx-template

Replace {placeholders} and manage content inside .docx files.

---

---

• Primitive: not a template engine, but can do quite a few transformations
  ^{Replace text, swap images, delete comments, flip checkboxes, insert custom markup}

• Fast: single-pass, avoids recompression, uses Aho-Corasick internally, almost O(n)
  ^{No long time read issues like docx‑rs has}

• Not memory-efficient (yet): operates on a byte stream without DOM tree allocation
  ^{Keeps the whole text in‑memory}

Example

use docx_template::DocxFile;
use serde::Serialize;
use std::error::Error;

fn main() -> Result<(), Box<Error>> {
    let data = Data { crustacean: "🦀".into() };
    let output = DocxFile::from_path("in.docx")?.into_template(data)?.render()?;
    std::fs::write("output.docx", output)?;
    Ok(())
}

#[derive(Serialize)]
struct Data {
    crustacean: String
}

Why

A naive approach to the problem is just calling xml.replace("{placeholder}", "🦀"). Which isn't 100% accurate, as placeholders can reside in multiple adjacent XML nodes like in the example below. That's why this crate was made. It reads XML nodes, detects patterns, and applies transformations keeping the structural integrity.

<w:run>{place</w:run><w:run>holder}</w:run>
<w:run>🦀</w:run><w:run></w:run>

Features

• serde (default) — use json! macro & Serialize structs to create templates
• docx-rs — insert markup defined by @bokuweb/docx‑rs
• docx-rust — insert markup defined by @cstkingkey/docx‑rust

Ecosystem

name	description
@bokuweb/docx‑rs 0.4.18 Apr 26, 2024	DOM tree contains owned values User-friendly naming and structure Reference ids must be set manually, despite automatic increments 🔥 Lots of examples docx-template = { feature = ["docx-rs"] }
@cstkingkey/docx‑rust 0.1.8 May 21, 2024	DOM tree has a 'lifetime parameter Close-to-spec naming and structure Reference ids must be set manually docx-template = { feature = ["docx-rust"] }
@yūdachi/docx 1.1.2 Apr 27, 2020	💀 (forked by docx-rust)
@kaisery/ooxmlsdk 0.1.16 Oct 12, 2024	Inspired by .NET Open XML SDK Low-level, generated from specification Early development stage
office-crypto	Allows decrypting password protected MS Office files
ms-offcrypto-writer	Encrypting ECMA376/OOXML files with agile encryption

Note

Office Open XML (also informally known as OOXML or Microsoft Open XML (MOX)) is a zipped, XML-based file format developed by Microsoft for representing spreadsheets, charts, presentations and word processing documents. The format was initially standardized by Ecma (as ECMA-376), and by the ISO and IEC (as ISO/IEC 29500) in later versions.