Uniword is Microsoft Word’s feature set, scripted. Every Ribbon tab, dialog, and pane that produces or inspects document content has a CLI command or Ruby API equivalent — with perfect OOXML round-trip fidelity, deterministic output, and three-layer verification that goes beyond what Word itself can check.

Version 1.4.0 — covers 760 OOXML elements across 22 namespaces.

1. Why uniword

  • Scriptable Word — Replace Word’s UI with one-shot CLI commands or a fluent Ruby API. No COM, no headless Office, no GUI dependency.

  • 100% round-trip fidelity — Every OOXML element preserved across load-modify-save. ISO documents round-trip with zero normative differences.

  • Verification beyond Word — Three-layer pipeline: OPC package, XSD schema, and 15+ semantic rules. uniword verify --xsd is stricter than Word’s own "Check for Issues".

  • Deterministic output — Stable rIds via Docx::IdAllocator. The same input always produces the same ZIP — diff-friendly for git.

  • Repair with reporting — uniword repair shows every applied fix with a code and message. Word’s repair is silent.

  • Byte-for-byte unmodelled parts — VBA projects, glossary documents, custom XML, embedded objects: anything uniword doesn’t model is preserved verbatim instead of dropped.

2. Start here: Word for the command line

If you are new to uniword, the fastest on-ramp is the master Word UI → CLI / API mapping. It shows side-by-side what each Word feature looks like as a uniword command or Ruby call:

→ Word for the command line

The 60-second tour from that page:

uniword convert brief.html brief.docx
uniword theme apply brief.docx themed.docx --name meridian
uniword styleset apply themed.docx styled.docx --name signature
uniword fonts replace styled.docx defonted.docx --from Calibri --to Carlito
uniword page setup defonted.docx paged.docx --size a4 --margins 2cm
uniword toc insert paged.docx
uniword watermark add paged.docx "DRAFT"
uniword headers add-footer paged.docx "Page "
uniword spellcheck check paged.docx
uniword protect apply paged.docx --mode tracked_changes
uniword verify final.docx --xsd

3. Quick Navigation

3.1. By Your Role

Ruby Developer

Start with Quick Start, then Ruby API and Builder API.

Technical Writer

Start with Themes and StyleSets, then Theme Catalog for the full list.

QA Engineer

Start with Three-Layer Pipeline for DOCX verification, then verify.

DevOps

Start with CLI for command-line conversion and Format Conversion for batch processing.

Contributor

Start with Contributing then Adding OOXML Elements.

3.2. By Task

Create a document from code
Open and modify an existing DOCX
Apply themes and styles
Replace fonts across a document
Lay out pages
Manage styles
Repair a broken document
Validate DOCX files
Convert formats

4. What’s new

4.1. 1.4.0 (July 2026)

  • Unmodelled parts preserved byte-for-byte — VBA projects, glossary documents, docProps/meta.xml, custom XML, header/comment .rels sidecars round-trip verbatim via Docx::RawPart.

  • MCE-aware XSD validation — uniword verify --xsd no longer drowns in false positives for w14:paraId, mc:Ignorable, and other MCE extension content real documents always carry.

  • uniword repair — Reconcile and report; the Reconciler’s deterministic fixes surfaced as a one-shot command with per-fix codes.

  • uniword styles rename / remove — Word’s style rename and the Styles-pane cleanup as commands.

  • uniword page setup — Word’s Page Setup dialog (size, orientation, margins) as a command.

  • uniword fonts replace — Word’s Replace Fonts dialog as a one-shot command.

  • uniword theme fonts / colors — Word’s Design → Fonts and Design → Colors galleries as commands.

  • Comment authoring and word/comments.xml round-trip — Builder#comment anchors a comment around a paragraph; comments survive load-modify-save.

  • Write-time integrity gate — PackageIntegrityChecker refuses to write a broken package; saves raise Uniword::ValidationError with structured issues.

  • Consolidated validation engine — Validation::Engine runs the same rule registry for validate, verify, and DocumentRoot#valid?.

  • New model-level rules — DOC-200 (body required), DOC-201/202 (bookmark pairing and uniqueness), DOC-203 (empty paragraphs), DOC-204/205 (tbl requires tblGrid/tblPr).

See the CHANGELOG for the full history.

5. Learning Path

5.1. Level 1: Get Started (5 minutes)

  1. Install Uniword

  2. Try basic examples

  3. Understand core concepts

5.2. Level 2: See the Word mapping (10 minutes)

  1. Word for the command line

5.3. Level 3: Learn Interfaces (15 minutes)

Choose your interface:

  • Ruby API — Build documents programmatically

  • CLI — Command-line usage

5.4. Level 4: Follow Guides (30 minutes)

  1. Text Formatting

  2. Tables

  3. Themes

  4. StyleSets

  5. Round-Trip Fidelity

5.5. Level 5: Understand the Design (1 hour)

  1. Architecture overview

  2. Schema-driven generation

  3. Prevention Layer

5.6. Level 6: Master Features (As needed)

  1. 29 bundled themes

  2. 12 bundled stylesets

  3. 23 color schemes

  4. Custom validation rules

6. Getting Help

Found a bug?

Report an issue on GitHub

Have a question?

Search this documentation or check the CLI reference

Want to contribute?

See Contributing to Uniword