DOCX creation, editing, and analysis

Overview

A .docx file is a ZIP archive containing XML files.

Quick Reference

Task	Approach
Read/analyze content	INLINECODE0 or unpack for raw XML
Create new document

Use docx-js - see Creating New Documents below | | Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |

Converting .doc to .docx

Legacy .doc files must be converted before editing:

CODEBLOCK0

Reading Content

CODEBLOCK1

Converting to Images

CODEBLOCK2

Accepting Tracked Changes

To produce a clean document with all tracked changes accepted (requires LibreOffice):

CODEBLOCK3

---

Creating New Documents

Generate .docx files with JavaScript, then validate. Install: INLINECODE3

Setup

CODEBLOCK4

Validation

After creating the file, validate it. If validation fails, unpack, fix the XML, and repack. CODEBLOCK5

Page Size

CODEBLOCK6

Common page sizes (DXA units, 1440 DXA = 1 inch):

Paper	Width	Height	Content Width (1" margins)
US Letter	12,240	15,840	9,360
A4 (default)

11,906 | 16,838 | 9,026 |

Landscape orientation: docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
CODEBLOCK7

Styles (Override Built-in Headings)

Use Arial as the default font (universally supported). Keep titles black for readability.

CODEBLOCK8

Lists (NEVER use unicode bullets)

CODEBLOCK9

Tables

CRITICAL: Tables need dual widths - set both columnWidths on the table AND width on each cell. Without both, tables render incorrectly on some platforms.

CODEBLOCK10

Table width calculation:

Always use WidthType.DXA — WidthType.PERCENTAGE breaks in Google Docs.

CODEBLOCK11

Width rules:

• - Always use WidthType.DXA — never WidthType.PERCENTAGE (incompatible with Google Docs)
• Table width must equal the sum of INLINECODE10
• Cell width must match corresponding INLINECODE12
• Cell margins are internal padding - they reduce content area, not add to cell width
• For full-width tables: use content width (page width minus left and right margins)

Images

CODEBLOCK12

Page Breaks

CODEBLOCK13

Table of Contents

CODEBLOCK14

Headers/Footers

CODEBLOCK15

Critical Rules for docx-js

• - Set page size explicitly - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
• Landscape: pass portrait dimensions - docx-js swaps width/height internally; pass short edge as width, long edge as height, and set INLINECODE16
• Never use \n - use separate Paragraph elements
• Never use unicode bullets - use LevelFormat.BULLET with numbering config
• PageBreak must be in Paragraph - standalone creates invalid XML
• ImageRun requires type - always specify png/jpg/etc
• Always set table width with DXA - never use WidthType.PERCENTAGE (breaks in Google Docs)
• Tables need dual widths - columnWidths array AND cell width, both must match
• Table width = sum of columnWidths - for DXA, ensure they add up exactly
• Always add cell margins - use margins: { top: 80, bottom: 80, left: 120, right: 120 } for readable padding
• Use ShadingType.CLEAR - never SOLID for table shading
• TOC requires HeadingLevel only - no custom styles on heading paragraphs
• Override built-in styles - use exact IDs: "Heading1", "Heading2", etc.
• Include outlineLevel - required for TOC (0 for H1, 1 for H2, etc.)

---

Editing Existing Documents

Follow all 3 steps in order.

Step 1: Unpack

python scripts/office/unpack.py document.docx unpacked/

Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (“ etc.) so they survive editing. Use --merge-runs false to skip run merging.

Step 2: Edit XML

Edit files in unpacked/word/. See XML Reference below for patterns.

Use "Claude" as the author for tracked changes and comments, unless the user explicitly requests use of a different name.

Use the Edit tool directly for string replacement. Do not write Python scripts. Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.

CRITICAL: Use smart quotes for new content. When adding text with apostrophes or quotes, use XML entities to produce smart quotes:

<!-- Use these entities for professional typography -->
<w:t>Here&#x2019;s a quote: &#x201C;Hello&#x201D;</w:t>

Entity	Character
INLINECODE30	‘ (left single)
INLINECODE31

’ (right single / apostrophe) |
| “ | “ (left double) |
| ” | ” (right double) |

Adding comments: Use comment.py to handle boilerplate across multiple XML files (text must be pre-escaped XML):

python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"  # custom author name

Then add markers to document.xml (see Comments in XML Reference).

Step 3: Pack

python scripts/office/pack.py unpacked/ output.docx --original document.docx

Validates with auto-repair, condenses XML, and creates DOCX. Use --validate false to skip.

Auto-repair will fix:

• - durableId >= 0x7FFFFFFF (regenerates valid ID)
• Missing xml:space="preserve" on <w:t> with whitespace

Auto-repair won't fix:

• - Malformed XML, invalid element nesting, missing relationships, schema violations

Common Pitfalls

• - Replace entire <w:r> elements: When adding tracked changes, replace the whole <w:r>...</w:r> block with <w:del>...<w:ins>... as siblings. Don't inject tracked change tags inside a run.
• Preserve <w:rPr> formatting: Copy the original run's <w:rPr> block into your tracked change runs to maintain bold, font size, etc.

---

XML Reference

Schema Compliance

• - Element order in <w:pPr>: <w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>, <w:rPr> last
• Whitespace: Add xml:space="preserve" to <w:t> with leading/trailing spaces
• RSIDs: Must be 8-digit hex (e.g., 00AB1234)

Tracked Changes

Insertion:
CODEBLOCK20

Deletion:
CODEBLOCK21

Inside <w:del>: Use <w:delText> instead of <w:t>, and <w:delInstrText> instead of <w:instrText>.

Minimal edits - only mark what changes:
CODEBLOCK22

Deleting entire paragraphs/list items - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add <w:del/> inside <w:pPr><w:rPr>:

<w:p>
  <w:pPr>
    <w:numPr>...</w:numPr>  <!-- list numbering if present -->
    <w:rPr>
      <w:del w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z"/>
    </w:rPr>
  </w:pPr>
  <w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
    <w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r>
  </w:del>
</w:p>

Without the <w:del/> in <w:pPr><w:rPr>, accepting changes leaves an empty paragraph/list item.

Rejecting another author's insertion - nest deletion inside their insertion:
CODEBLOCK24

Restoring another author's deletion - add insertion after (don't modify their deletion):
CODEBLOCK25

Comments

After running comment.py (see Step 2), add markers to document.xml. For replies, use --parent flag and nest markers inside the parent's.

CRITICAL: <w:commentRangeStart> and <w:commentRangeEnd> are siblings of <w:r>, never inside <w:r>.

CODEBLOCK26

Images

1. 1. Add image file to INLINECODE69
2. Add relationship to word/_rels/document.xml.rels:

<Relationship Id="rId5" Type=".../image" Target="media/image1.png"/>

1. 3. Add content type to [Content_Types].xml:

<Default Extension="png" ContentType="image/png"/>

1. 4. Reference in document.xml:

<w:drawing>
  <wp:inline>
    <wp:extent cx="914400" cy="914400"/>  <!-- EMUs: 914400 = 1 inch -->
    <a:graphic>
      <a:graphicData uri=".../picture">
        <pic:pic>
          <pic:blipFill><a:blip r:embed="rId5"/></pic:blipFill>
        </pic:pic>
      </a:graphicData>
    </a:graphic>
  </wp:inline>
</w:drawing>

---

Dependencies

• - pandoc: Text extraction
• docx: npm install -g docx (new documents)
• LibreOffice: PDF conversion (auto-configured for sandboxed environments via scripts/office/soffice.py)
• Poppler: pdftoppm for images