rusdox 0.1.1

Generate DOCX and PDF from YAML at Rust speed.
Documentation

RusDox

Rust Tests License OOXML Version

One readable spec → editable DOCX + native PDF, at Rust speed, without Word or LibreOffice.

Website · Documentation · Gallery · Releases · crates.io · Roadmap · Discussions

RusDox turns YAML into real DOCX and PDF output

See the full workflow in 24 seconds

Animated RusDox workflow from checksum-verified install to YAML editing and real DOCX/PDF output

The final frame keeps the YAML input beside both outputs. Inspect the real files: YAML source, editable DOCX, and native PDF.

RusDox is not just another YAML-to-document helper. It is a pure Rust document engine built for generating .docx and .pdf files programmatically, fast enough for serious automation.

If you have ever tried to create Word or PDF files in code, you already know the usual failure modes:

  • slow office runtimes
  • brittle conversions
  • poor control over layout
  • painful scaling when documents get large

RusDox keeps authoring simple with YAML and keeps the rendering path in Rust. The latest recorded 1,000-page stress run renders both DOCX and PDF in 679.86 ms in release mode. See the benchmark methodology and limitations before comparing it with another system.

Install in 10 seconds

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/OthmaneBlial/rusdox/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/OthmaneBlial/rusdox/main/scripts/install.ps1 | iex

Rust users can also install from crates.io:

cargo install rusdox --locked
# or, when cargo-binstall is available
cargo binstall rusdox

Release installers verify the archive against the published SHA256SUMS file before installing it.

Create and render the first document:

mkdir my-rusdox-docs && cd my-rusdox-docs
rusdox init-doc mydoc.yaml
rusdox mydoc.yaml

Outputs:

  • generated/mydoc.docx — editable Word document
  • rendered/mydoc.pdf — native PDF preview

See Getting started for the complete two-minute walkthrough.

Why It Lands

  • Generate a 1000-page DOCX and PDF pair in under a second in release mode.
  • Create large files without Word, LibreOffice, or an external office runtime.
  • Keep authoring readable with YAML while the heavy lifting stays in Rust.
  • Validate specs before render so semantic issues fail early in CI and local workflows.
  • Rebuild documents automatically while editing specs or config files.
  • Benchmark real parse, validation, compose, DOCX, and PDF timings from the CLI.
  • Keep simple authoring in YAML longer with variables, includes, and repeaters.
  • Set document metadata such as title, author, subject, keywords, and custom properties directly from specs or Rust.
  • Use one tool for recurring reports, invoices, proposals, dashboards, and batch document jobs.

Real-World Use Cases

  • Executive and board reporting: recurring operating packs, KPI dashboards, and leadership reviews
  • Client-facing automation: proposals, invoices, onboarding packs, and launch briefs
  • Internal document infrastructure: batch exports, meeting notes, project briefs, and template-driven pipelines

Why RusDox instead of another pipeline?

Capability RusDox Office conversion pipeline DOCX-only library PDF typesetter
Editable DOCX output Yes Yes Yes Usually no
Native PDF output Yes No No Yes
Word/LibreOffice runtime required No Yes No No
Human-readable document spec Yes Varies Code-first Varies
Same typed model for both outputs Yes No No No
Automated DOCX/PDF parity report Planned for v0.2 No No No

RusDox does not claim complete OOXML coverage. Check the compatibility matrix for supported, partial, and intentionally unsupported behavior.

Benchmark Proof

RusDox stress benchmark

Latest 1000-page YAML stress run:

  • Generator: ./scripts/generate_stress_yaml.sh
  • Dev: ./scripts/run_stress_yaml.sh
  • Dev timings: 176.81 ms parse, 34.23 ms compose, 285.66 ms DOCX, 289.04 ms PDF, 785.78 ms total
  • Release: ./scripts/run_stress_yaml.sh --release
  • Release timings: 132.78 ms parse, 27.78 ms compose, 234.32 ms DOCX, 284.91 ms PDF, 679.86 ms total

That is the real value proposition: RusDox is for generating very large Word and PDF files programmatically without the usual office stack overhead.

First document

Create a starter doc:

mkdir my-rusdox-docs
cd my-rusdox-docs
rusdox init-doc mydoc.yaml

Edit mydoc.yaml:

output_name: client-brief
blocks:
  - type: title
    text: Client Brief
  - type: subtitle
    text: Q2 rollout
  - type: section
    text: Summary
  - type: body
    text: Launch is approved pending final security FAQ wording.
  - type: bullets
    items:
      - Pricing is approved.
      - Support macros are in review.
      - Commercial release is planned for April 7.

Generate the files:

rusdox mydoc.yaml

You get:

  • generated/client-brief.docx
  • rendered/client-brief.pdf

Render a whole folder of YAML docs:

rusdox examples

Validate before rendering:

rusdox validate mydoc.yaml
rusdox validate examples --format json

Watch a spec while editing:

rusdox watch mydoc.yaml

Benchmark a render path:

rusdox bench examples/stress/stress_1000_pages.yaml --iterations 5 --warmup 1

What Makes It Different

  • Pure Rust .docx generation
  • Pure Rust PDF rendering
  • No Word dependency
  • No LibreOffice dependency
  • Human-readable YAML examples
  • Config-driven styling through rusdox.toml
  • Reusable named paragraph, run, and table styles with inheritance
  • YAML composition features for variables, includes, and repeaters
  • First-class document metadata in specs and the Rust API
  • First-class validate, watch, and bench CLI workflows

Examples

examples/ is now a folder of YAML document specs.

Highlights:

  • examples/board_report.yaml
  • examples/executive_dashboard.yaml
  • examples/product_launch_brief.yaml
  • examples/talent_profile.yaml
  • examples/formatting_showcase.yaml
  • examples/named_styles_showcase.yaml
  • examples/visual_assets_showcase.yaml
  • examples/yaml_composition_showcase.yaml
  • examples/stress/stress_1000_pages.yaml

More detail is in examples/README.md.

Template Gallery

RusDox template gallery

Browse the gallery:

Docs

The full documentation lives in docs/.

Start here:

Configuration

The easiest way to tweak styling is the CLI wizard, not manual TOML editing:

rusdox config path
rusdox config wizard --level basic
rusdox config wizard --level advanced

The install script creates a user config at ~/rusdox/config.toml when it does not exist yet.

Use it to control:

  • fonts
  • spacing
  • colors
  • table defaults
  • output folders
  • PDF preview behavior

If you want settings only for one project, create a local override:

rusdox config wizard --path ./rusdox.toml --level basic

Load order is:

  • ./rusdox.toml
  • ~/rusdox/config.toml
  • built-in defaults

The goal is simple:

  • content lives in YAML
  • styling lives in config
  • speed lives in Rust

Advanced

If you need full control, dynamic generation, or lower-level document work, RusDox still exposes the Rust API.

See docs/rust-api.md. The full docs index is in docs/README.md.

That doc covers:

  • cargo add rusdox
  • direct Rust document construction
  • config-driven Studio usage
  • legacy .rs script execution
  • low-level API notes

Community

If you want to contribute or report something:

Status

The current foundation focuses on fast, typed support for:

  • paragraphs
  • runs and common text formatting
  • tables, rows, and cells
  • named paragraph, run, and table styles with inheritance
  • image, logo, signature, and SVG/chart blocks
  • plain-text extraction
  • config-driven composition
  • YAML/JSON/TOML document specs

Current limitations are documented rather than hidden. High-level specs do not yet expose hyperlinks, bookmarks, footnotes, comments, tracked changes, automatic tables of contents, merged cells, or Word-native placeholder templates. PDF currently uses its own configured page geometry and does not yet mirror DOCX headers, footers, or page-number fields. Follow the compatibility matrix and roadmap for the exact contract and planned parity work.

Development

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test