Document Docx

Document DOCX Skill - Quick Reference

This skill covers creation, editing, review, extraction, and release workflows for .docx documents.

Modern best practices (Jul 2026):

• Treat .docx as the editable source and PDF as a release artifact.
• Prefer templates and built-in styles over manual formatting.
• Use comments for review notes; use Word Compare for true redlines.
• For LLM/RAG extraction, optimize for structure, trust level, and sanitization rather than visual fidelity.
• Treat macro-enabled Office files (.docm, .dotm) as untrusted by default.
• Before promising a feature (comments, alt text, tracked changes), check the installed library version — several of these APIs are recent additions and silently absent on older pins. See "Version-Gate Before Promising A Feature" below.

Core Decision Rules (2026)

• If non-developers need to own layout/design, prefer docxtpl with a Word-authored template.
• If the stack is Python and edits are structural, prefer python-docx.
• If the stack is TypeScript/Node and the output is generated server-side, prefer docx.
• If you need semantic HTML from a trusted document, prefer mammoth, then sanitize before rendering or storing the output.
• If you need Markdown/JSON for search, indexing, or RAG, prefer MarkItDown or Docling.
• If the user asks for tracked changes, do not promise high-level library support. Generate a revised .docx and use Word Compare, or switch to OOXML-specialized tooling.
• If the user asks for PDF output, prefer Word automation for highest fidelity and LibreOffice headless for cross-platform batch workflows.
• If the input is .doc, convert to .docx first. If it is .docm or .dotm, do not trust embedded macros.

Quick Reference

Selection Guide

• Prefer docxtpl when a legal, ops, or business user needs to maintain the template in Word.
• Prefer python-docx for moderate formatting complexity where you control the document structure in code.
• Prefer docx when the surrounding service and tests already live in Node.js.
• Prefer mammoth for trusted, text-first conversion to HTML; it is not a fidelity-preserving renderer.
• Prefer MarkItDown for simple DOCX-to-Markdown pipelines.
• Prefer Docling when DOCX is only one input among many formats or you need HTML/JSON/Markdown/text output from a unified pipeline.

ASCII Flow

DOCX request
  |
  v
Classify file + trust level
  |-- .docx / .dotx -----> normal OOXML workflow
  |-- .doc -------------> convert to .docx first
  |-- .docm / .dotm ----> treat macros as untrusted
  |
  v
Choose lane
  |-- Word-owned template ------> docxtpl
  |-- Python structural edit ---> python-docx
  |-- Node service generation --> docx
  |-- trusted HTML conversion --> mammoth + sanitizer
  |-- Markdown / JSON ingest ---> MarkItDown or Docling
  |-- tracked-change review ----> revised DOCX + Word Compare
  |
  v
Generate, edit, or extract
  |
  v
Quality gate
  |-- parseability + unresolved tags ---> scripts/docx_quality_gate.py
  |-- comments / revisions / OOXML ----> scripts/docx_inspect_ooxml.py
  |
  v
Viewer, accessibility, and release checks

Format And Safety Caveats

• .docx and .dotx are Office Open XML packages; .doc is legacy binary and needs conversion first.
• .docm and .dotm are macro-enabled; do not treat them as safe content inputs.
• python-docx can add and read comments in the main document body, but not threaded replies/resolved states, and not comment anchors in headers/footers.
• python-docx does not provide reliable tracked-change authoring.
• mammoth performs no sanitization of generated HTML or links from untrusted source documents.
• Tables of contents and many Word fields are placeholders until updated in Word.

Version-Gate Before Promising A Feature

Do not assume the environment has a current library. This is the single most common way this skill causes a confident-but-wrong answer:

• Document.add_comment() only exists from python-docx 1.2.0 onward. On an older pinned version it raises AttributeError, not a graceful fallback. Check first: python -c "import docx; print(docx.__version__)".
• python-docx still has no public high-level property for image alt text (no .alt_text on InlineShape) as of the current 1.x line — InlineShape only documents height, width, and type. The OOXML workaround in references/accessibility-compliance.md reaches into the private _inline attribute; treat that as an implementation detail that can move between releases, re-verify after any python-docx upgrade, and prefer python-docx's own comment/style APIs wherever a public one exists instead of private attributes.
• If a user asks for a feature this skill flags as unsupported (tracked-change authoring, threaded comment replies, resolved-state comments), say so plainly rather than approximating it with formatting hacks — a document that merely looks right (e.g., colored/struck-through text standing in for <w:ins>/<w:del>) will fail any real redline/legal review because it carries no revision metadata.

Default Workflow

1. Identify the file type and trust level: .docx/.dotx vs .docm/.dotm vs legacy .doc.
2. Pick the lane:

• Template generation -> docxtpl
• Programmatic structure edits -> python-docx or docx
• Review/comments -> comments or Word Compare
• LLM extraction -> MarkItDown, Docling, or mammoth

1. Generate or modify the document.
2. Run scripts/docx_quality_gate.py and, when needed, scripts/docx_inspect_ooxml.py.
3. If shipping externally, validate rendering in Word plus at least one secondary viewer and apply accessibility hygiene.

Core Operations

Create A Document (Python - python-docx)

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.shared import Inches

doc = Document()

title = doc.add_heading("Quarterly Review", 0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER

doc.add_paragraph("Executive summary goes here.")

table = doc.add_table(rows=2, cols=2)
table.style = "Table Grid"
table.rows[0].cells[0].text = "Metric"
table.rows[0].cells[1].text = "Value"
table.rows[1].cells[0].text = "Revenue"
table.rows[1].cells[1].text = "$1.2M"

doc.add_picture("chart.png", width=Inches(4.5))
doc.save("quarterly-review.docx")

Add A Review Comment (Python - python-docx)

from docx import Document

doc = Document()
paragraph = doc.add_paragraph("This clause needs legal review.")

comment = doc.add_comment(
    runs=paragraph.runs,
    text="Clarify whether this applies to renewals as well.",
    author="Legal",
    initials="LG",
)

comment.paragraphs[0].add_run(" Add the renewal edge case explicitly.").bold = True