DocgenTry it

DOCX fidelity — what survives, what doesn't

Docgen renders three formats from one source: HTML, PDF (via Chromium), and DOCX (via PhpOffice/PhpWord). HTML and PDF look identical. DOCX doesn't, and that's a deliberate tradeoff worth understanding before you build a workflow that relies on it.

The short version

Use DOCX when:

  • The recipient needs to edit the document in Word or Google Docs.
  • The layout is predominantly paragraphs, headings, tables, and lists.
  • Visual fidelity is a "nice to have," not a contract requirement.

Don't use DOCX when:

  • The layout depends on flexbox, grid, absolute positioning, or transforms.
  • The document is a brand artifact where typography and spacing must be pixel-precise (offer letters with sealed corporate identity, certificates with award-grade typography, etc.). Render those as PDF.
  • Your downstream tooling expects PDF/A or any other archival format.

What survives the conversion

  • Block-level structure — paragraphs, headings (h1–h6), block quotes, horizontal rules.
  • Inline formatting — bold, italic, underline, strike-through, links.
  • Lists — ordered (ol) and unordered (ul), nested up to ~3 levels.
  • Tables — table / thead / tbody / tr / td / th with column widths in absolute units (px, pt).
  • Basic CSS — color, background-color,font-family(when the font is also installed on the recipient's system), font-size (in pt or px),font-weight, text-align, margin,padding, border (single-color, single-style only).
  • Images — img tags referencing reachable URLs are embedded.

What doesn't survive

  • Flexbox and Grid — DOCX has no equivalent. Flex containers collapse to inline-block placement; multi-column grids render as a single column.
  • Absolute or fixed positioning — anything with position: absolute or position: fixed becomes inline content. Ornamental borders, watermarks, and decorative overlays usually break.
  • @page directives— page sizes, margins, headers, and footers defined in CSS don't transfer.
  • CSS gradients, transforms, filters — silently dropped.
  • Web fonts loaded via @import or <link>— the renderer can't embed font files into the DOCX archive; fonts have to exist on the recipient's system.
  • Custom-element-driven layouts— anything assembled via client-side JavaScript or web components doesn't exist by the time PhpWord sees the markup.

How to author for both PDF and DOCX

The three reference templates that ship with docgen follow this pattern:

  1. Layout uses flow positioning, not flexbox/grid. Headers stack above content; columns are real <table> columns, not flex children.
  2. Spacing is in pt or px, not rem or em.
  3. Borders are single-color, single-style. No multi-color or double borders.
  4. Print-only styling lives in @media print. PDF picks it up; DOCX ignores it cleanly.

Worked examples

The reference templates demonstrate three different fidelity levels:

  • Invoice — renders to PDF and DOCX with substantially the same layout. The header is a <table>, the line items are a <table>, totals are right-aligned via text-align: right. Both formats are usable.
  • Offer letter — friendliest case for DOCX: serif body, single column, embedded <dl> for terms, signature lines at the bottom. Editable in Word with paragraphs spaced correctly.
  • Certificate — landscape @page directive, absolute-positioned ornamental borders, flex layout. None of that has a DOCX equivalent. PDF is a polished award certificate; DOCX is a single-column letter-format document with the same text. This is a PDF-only template.

Roadmap

DOCX fidelity is the most-asked-about gap. Two features that would close most of it:

  • Native DOCX templates — upload a .docx file with merge-field syntax, instead of HTML+Twig. Trades multi-format-from-one-source for highest-fidelity DOCX. v2 feature.
  • LibreOffice headless for DOCX → PDF— replace PhpWord's in-process converter with a LibreOffice subprocess. Higher fidelity at the cost of installing LibreOffice. Worth it for a real customer; out of scope for the demo.

If your use case is "the output needs to look exactly like the design," render as PDF and hand DOCX customers a PDF too. That's how Stripe, Figma, Notion, and every other modern SaaS handle it.