docx-custom

name: docx-custom description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."

DOCX creation, editing, and analysis

Intent Router

Load this skill's sections based on the task:

• Creating new documents → Read "Creating New Documents" section for docx-js library patterns
• Editing existing documents → Read "Editing Existing Documents" for unpack/repack workflow and XML patterns
• XML reference → Load "XML Reference" for tracked changes, comments, images, and schema patterns
• Page size / layout issues → Check "Page Size" and "Critical Rules" sections
• Table formatting problems → See "Tables" section for dual-width requirements

Overview

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

Quick Reference

Converting .doc to .docx

Legacy .doc files must be converted before editing:

python office-custom/scripts/soffice.py --headless --convert-to docx document.doc

Reading Content

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

# Raw XML access
python office-custom/scripts/unpack.py document.docx unpacked/

Converting to Images

python office-custom/scripts/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

Accepting Tracked Changes

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

python docx-custom/scripts/accept_changes.py input.docx output.docx

Creating New Documents

Generate .docx files with JavaScript, then validate. Install docx in the working directory that contains your generation script:

npm install docx

Setup

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
        TabStopType, TabStopPosition, Column, SectionType,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak, NumberFormat,
        LineNumberRestartFormat } = require('docx');

const doc = new Document({ sections: [{ children: [/* content */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Validation

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

python office-custom/scripts/validate.py doc.docx
python office-custom/scripts/lint_docx.py doc.docx

docx-js list numbering can produce a lint_docx.py warning about missing Word-authored numbering metadata (w16cid:durableId / w15:restartNumberingAfterBreak). Treat warnings as review items: verify in Word when possible, or unpack/edit word/numbering.xml if the document must be warning-clean.

Page Size

// CRITICAL: docx-js defaults to A4, not US Letter
// Always set page size explicitly for consistent results
sections: [{
  properties: {
    page: {
      size: {
        width: 12240,   // 8.5 inches in DXA
        height: 15840   // 11 inches in DXA
      },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
    }
  },
  children: [/* content */]
}]

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

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

size: {
  width: 12240,   // Pass SHORT edge as width
  height: 15840,  // Pass LONG edge as height
  orientation: PageOrientation.LANDSCAPE  // docx-js swaps them in the XML
},
// Content width = 15840 - left margin - right margin (uses the long edge)

Styles (Override Built-in Headings)

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

const doc = new Document({
  styles: {
    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
    paragraphStyles: [
      // IMPORTANT: Use exact IDs to override built-in styles
      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 32, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 28, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }),
    ]
  }]
});

Lists (NEVER use unicode bullets)

// ❌ WRONG - never manually insert bullet characters
new Paragraph({ children: [new TextRun("• Item")] })  // BAD
new Paragraph({ children: [new TextRun("\u2022 Item")] })  // BAD

// ✅ CORRECT - use numbering config with LevelFormat.BULLET
const doc = new Document({
  numbering: {
    config: [
      { reference: "bullets",
        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
      { reference: "numbers",
        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ numbering: { reference: "bullets", level: 0 },
        children: [new TextRun("Bullet item")] }),
      new Paragraph({ numbering: { reference: "numbers", level: 0 },
        children: [new TextRun("Numbered item")] }),
    ]
  }]
});

// ⚠️ Each reference creates INDEPENDENT numbering
// Same reference = continues (1,2,3 then 4,5,6)
// Different reference = restarts (1,2,3 then 1,2,3)

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.

// CRITICAL: Always set table width for consistent rendering
// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgrounds
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };

new Table({
  width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)
  columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)
  rows: [
    new TableRow({
      children: [
        new TableCell({
          borders,
          width: { size: 4680, type: WidthType.DXA }, // Also set on each cell
          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLID
          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)
          children: [new Paragraph({ children: [new TextRun("Cell")] })]
        })
      ]
    })
  ]
})

Table width calculation:

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

// Table width = sum of columnWidths = content width
// US Letter with 1" margins: 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360]  // Must sum to table width

Width rules:

• Always use WidthType.DXA — never WidthType.PERCENTAGE (incompatible with Google Docs)
• Table width must equal the sum of columnWidths
• Cell width must match corresponding columnWidth
• 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

// CRITICAL: type parameter is REQUIRED
new Paragraph({
  children: [new ImageRun({
    type: "png", // Required: png, jpg, jpeg, gif, bmp, svg
    data: fs.readFileSync("image.png"),
    transformation: { width: 200, height: 150 },
    altText: { title: "Title", description: "Desc", name: "Name" } // All three required
  })]
})

Page Breaks

// CRITICAL: PageBreak must be inside a Paragraph
new Paragraph({ children: [new PageBreak()] })

// Or use pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("New page")] })

Hyperlinks

// External link
new Paragraph({
  children: [new ExternalHyperlink({
    children: [new TextRun({ text: "Click here", style: "Hyperlink" })],
    link: "https://example.com",
  })]
})

// Internal link (bookmark + reference)
// 1. Create bookmark at destination
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
  new Bookmark({ id: "chapter1", children: [new TextRun("Chapter 1")] }),
]})
// 2. Link to it
new Paragraph({ children: [new InternalHyperlink({
  children: [new TextRun({ text: "See Chapter 1", style: "Hyperlink" })],
  anchor: "chapter1",
})]})

Footnotes

const doc = new Document({
  footnotes: {
    1: { children: [new Paragraph("Source: Annual Report 2024")] },
    2: { children: [new Paragraph("See appendix for methodology")] },
  },
  sections: [{
    children: [new Paragraph({
      children: [
        new TextRun("Revenue grew 15%"),
        new FootnoteReferenceRun(1),
        new TextRun(" using adjusted metrics"),
        new FootnoteReferenceRun(2),
      ],
    })]
  }]
});

Tab Stops

// Right-align text on same line (e.g., date opposite a title)
new Paragraph({
  children: [
    new TextRun("Company Name"),
    new TextRun("\tJanuary 2025"),
  ],
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

// Dot leader (e.g., TOC-style)
new Paragraph({
  children: [
    new TextRun("Introduction"),
    new TextRun({ children: [
      new PositionalTab({
        alignment: PositionalTabAlignment.RIGHT,
        relativeTo: PositionalTabRelativeTo.MARGIN,
        leader: PositionalTabLeader.DOT,
      }),
      "3",
    ]}),
  ],
})

Multi-Column Layouts

// Equal-width columns
sections: [{
  properties: {
    column: {
      count: 2,          // number of columns
      space: 720,        // gap between columns in DXA (720 = 0.5 inch)
      equalWidth: true,
      separate: true,    // vertical line between columns
    },
  },
  children: [/* content flows naturally across columns */]
}]

// Custom-width columns (equalWidth must be false)
sections: [{
  properties: {
    column: {
      equalWidth: false,
      children: [
        new Column({ width: 5400, space: 720 }),
        new Column({ width: 3240 }),
      ],
    },
  },
  children: [/* content */]
}]

Force a column break with a new section using type: SectionType.NEXT_COLUMN.

Table of Contents

// CRITICAL: Headings must use HeadingLevel ONLY - no custom styles
new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })

Headers/Footers

sections: [{
  properties: {
    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 inch
  },
  headers: {
    default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
    })] })
  },
  children: [/* content */]
}]

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 orientation: PageOrientation.LANDSCAPE
• 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
• Never use tables as dividers/rules - cells have minimum height and render as empty boxes (including in headers/footers); use border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } } on a Paragraph instead. For two-column footers, use tab stops (see Tab Stops section), not tables
• 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 office-custom/scripts/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 Assistant as the default author for tracked changes and comments, unless the user explicitly requests 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>

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

python docx-custom/scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python docx-custom/scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0
python docx-custom/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 office-custom/scripts/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
• Preserves the default (prefix-less) namespace on .rels / [Content_Types].xml (no ns0: prefixes)
• Restores known namespace declarations listed in root mc:Ignorable when unpack.py / XML round-tripping stripped unused declarations

Auto-repair won't fix:

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

Editing package parts (.rels, [Content_Types].xml)

The package parts use a default (prefix-less) namespace. If you re-serialize them through a generic XML writer that doesn't know that namespace, you get <ns0:Relationships> / <ns0:Types> — still well-formed XML, but Word flags the file for recovery and LibreOffice may refuse to open it.

• Preserve the default namespace when re-writing these parts:
  • .rels → http://schemas.openxmlformats.org/package/2006/relationships
  • [Content_Types].xml → http://schemas.openxmlformats.org/package/2006/content-types
• With xml.etree.ElementTree, call register_namespace("", uri) for the part's namespace right before tostring (only one empty prefix can be registered globally, and these two namespaces differ — so register per file). pack.py and comment.py already do this; prefer editing part bytes in place over round-tripping them through a generic writer.
• Keep [Content_Types].xml as the first ZIP entry (pack.py handles this).
• After any content-type edit, ensure every part has a matching <Override> or a <Default> for its extension — a dropped override silently corrupts the package.

Verifying Output

A .docx opening in LibreOffice or passing well-formedness does NOT guarantee Word opens it without recovery. ZIP integrity, XML well-formedness, and a clean LibreOffice render are necessary but not sufficient. Before delivering, run the pre-delivery lint and, when possible, open the file in Word / Word Online:

python office-custom/scripts/validate.py output.docx    # structure + well-formedness
python office-custom/scripts/lint_docx.py output.docx   # silent-corruption signatures

lint_docx.py flags the silent corruptions that pass validate.py and render fine in LibreOffice but make Word repair on open: package parts serialized with a namespace prefix; numbering definitions missing w16cid:durableId / w15:restartNumberingAfterBreak; undeclared mc:Ignorable prefixes; tblPr child-order violations; and a table left as the last body block or adjacent to another table.

Validators passing is not proof Word will open the file cleanly. When a document still triggers Word's "we found a problem... repair?" dialog, diff your file against Word's ... - Repaired.docx (unzip both, compare the parts): the structural difference is the repair, once you ignore cosmetic resave noise (re-declared namespaces, rsid/paraId, proofErr, run merging, reordered [Content_Types]/rels). The lint_docx.py checks above cover the repairs seen most often; for anything new, add the signature to the linter.

LibreOffice-based rendering does not reserve space for a tall footer graphic the way Word does. A full-page render whose body text appears to run into a brand footer in a LibreOffice-converted PDF may be a conversion artifact, not a real Word collision — confirm against Word before treating it as a defect.

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.
• Don't prefix package parts: re-serializing .rels / [Content_Types].xml with ns0: prefixes triggers Word recovery — see "Editing package parts" above.
• Don't re-serialize word/document.xml with a reduced namespace set: if you rewrite the part through a generic XML writer, preserve the root's xmlns: declarations so every mc:Ignorable prefix still resolves. lint_docx.py flags undeclared mc:Ignorable prefixes, tblPr order, and trailing/adjacent tables — run it before delivery (see Verifying Output).

XML Reference

Schema Compliance

• Element order in <w:pPr>: <w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>, <w:rPr> last
• Element order in <w:tblPr>: <w:tblW> → <w:tblBorders> → <w:tblLook> (CT_TblPrBase). Appending <w:tblBorders> after <w:tblLook> is a schema violation Word silently repairs. With lxml, insert before tblLook (tblLook.addprevious(borders)), don't append.
• Last block before <w:sectPr> must be a paragraph: a <w:tbl> cannot be the final body element, and two <w:tbl> cannot be directly adjacent — Word repairs by inserting an empty <w:p/>. Add a spacer paragraph after any table whose next sibling is None, another <w:tbl>, or <w:sectPr>.
• mc:Ignorable prefixes must be declared: every prefix listed in a root mc:Ignorable="..." (on document.xml, headers, and footers) must resolve to an in-scope xmlns: declaration. Re-serializing a part with a minimized namespace set while leaving the original mc:Ignorable intact leaves prefixes undeclared — invalid Markup-Compatibility that triggers Word recovery even though validate.py stays green.
• Whitespace: Add xml:space="preserve" to <w:t> with leading/trailing spaces
• RSIDs: Must be 8-digit hex (e.g., 00AB1234)

Numbering and Lists (XML editing)

When adding a bullet or numbered list by hand-editing XML, prefer reusing an existing numId from the document's word/numbering.xml over fabricating a new definition. Most real templates already define bullet and ordered lists — scan for an existing <w:num> and point at its w:numId:

<!-- Reuse an existing list definition -->
<w:p>
  <w:pPr>
    <w:pStyle w:val="ListParagraph"/>
    <w:numPr><w:ilvl w:val="0"/><w:numId w:val="3"/></w:numPr>
  </w:pPr>
  <w:r><w:t>List item</w:t></w:r>
</w:p>

If you must create a definition, make it Word-faithful, not merely schema-legal. Word rebuilds the whole numbering part on open (its "recovery") when injected entries omit metadata that native definitions carry:

• give each new <w:num> a unique w16cid:durableId (scan existing values to avoid collisions) and declare xmlns:w16cid on the root;
• add w15:restartNumberingAfterBreak="0" to each new <w:abstractNum>;
• keep <w:abstractNum> elements before <w:num> elements (CT_Numbering order);
• keep <w:pPr> children in schema order inside list paragraphs (pStyle → numPr → ind);
• remove any literal leading bullet glyph (•, -, *) from run text once <w:numPr> is attached — the marker belongs in the list definition only.

<w:abstractNum w:abstractNumId="5">
  <w15:restartNumberingAfterBreak w:val="0"/>
  <w:lvl w:ilvl="0"><w:numFmt w:val="bullet"/><w:lvlText w:val="&#x2022;"/></w:lvl>
</w:abstractNum>
<w:num w:numId="7" w16cid:durableId="318492170">
  <w:abstractNumId w:val="5"/>
</w:num>

Run lint_docx.py (see Verifying Output) to catch numbering entries missing these attributes before delivery.

Suppressing built-in heading auto-numbering. Some templates' Heading 1/ Heading 2 styles carry list auto-numbering (e.g. Roman I, II, III...). For documents with manually-typed clause numbers this double-numbers (renders as III. 1. Scope). Suppress the style's numbering per heading paragraph with numId="0" (valid; means "no numbering"):

<w:pPr>
  <w:pStyle w:val="Heading1"/>
  <w:numPr><w:ilvl w:val="0"/><w:numId w:val="0"/></w:numPr>
</w:pPr>

Tracked Changes

Insertion:

<w:ins w:id="1" w:author="Assistant" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t>inserted text</w:t></w:r>
</w:ins>

Deletion:

<w:del w:id="2" w:author="Assistant" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>

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

Minimal edits - only mark what changes:

<!-- Change "30 days" to "60 days" -->
<w:r><w:t>The term is </w:t></w:r>
<w:del w:id="1" w:author="Assistant" w:date="...">
  <w:r><w:delText>30</w:delText></w:r>
</w:del>
<w:ins w:id="2" w:author="Assistant" w:date="...">
  <w:r><w:t>60</w:t></w:r>
</w:ins>
<w:r><w:t> days.</w:t></w:r>

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="Assistant" w:date="2025-01-01T00:00:00Z"/>
    </w:rPr>
  </w:pPr>
  <w:del w:id="2" w:author="Assistant" 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:

<w:ins w:author="Jane" w:id="5">
  <w:del w:author="Assistant" w:id="10">
    <w:r><w:delText>their inserted text</w:delText></w:r>
  </w:del>
</w:ins>

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

<w:del w:author="Jane" w:id="5">
  <w:r><w:delText>deleted text</w:delText></w:r>
</w:del>
<w:ins w:author="Assistant" w:id="10">
  <w:r><w:t>deleted text</w:t></w:r>
</w:ins>

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>.

<!-- Comment markers are direct children of w:p, never inside w:r -->
<w:commentRangeStart w:id="0"/>
<w:del w:id="1" w:author="Assistant" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>deleted</w:delText></w:r>
</w:del>
<w:r><w:t> more text</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>

<!-- Comment 0 with reply 1 nested inside -->
<w:commentRangeStart w:id="0"/>
  <w:commentRangeStart w:id="1"/>
  <w:r><w:t>text</w:t></w:r>
  <w:commentRangeEnd w:id="1"/>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="0"/></w:r>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="1"/></w:r>

Images (XML editing)

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

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

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

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

1. 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 docx in the working directory for new-document generation scripts
• LibreOffice: PDF conversion (auto-configured for sandboxed environments via office-custom/scripts/soffice.py)
• Poppler: pdftoppm for images

API Reference

Sources: python-docx docs, docx-js docs

python-docx (reading & editing existing .docx files)

Use python-docx when reading or programmatically inspecting existing Word documents.

Document

from docx import Document

doc = Document("file.docx")           # Load existing
doc = Document()                      # Create new (blank)
doc.save("output.docx")

Properties: paragraphs, tables, sections, styles, core_properties, inline_shapes, comments

Paragraph

para = doc.add_paragraph("Hello")
run = para.add_run(" world")
para.alignment = WD_ALIGN_PARAGRAPH.CENTER

Properties: text, runs, style, alignment, paragraph_format, hyperlinks, contains_page_break

Run

run = para.add_run("text")
run.bold = True
run.font.size = Pt(12)
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00)

Properties: text, bold, italic, underline, style, font, contains_page_break

run.add_break() defaults to a line break. For a page break pass the break type explicitly:

from docx.enum.text import WD_BREAK
run.add_break(WD_BREAK.PAGE)

A bare add_break() will not paginate.

Font

Table, Row, Cell

table = doc.add_table(rows=2, cols=3)   # apply borders via XML if no style exists
cell = table.cell(0, 0)
cell.text = "Header"
cell.merge(table.cell(0, 1))   # Merge cells

Don't assume Table Grid exists. table.style = "Table Grid" raises KeyError if the document/template doesn't define that style (many real templates ship only Normal Table, which has no borders). Either confirm the style exists in doc.styles, or apply borders directly in XML with a <w:tblBorders> block (respecting tblPr child order — see Schema Compliance).

Hyperlink

docx-js (creating new .docx from scratch)

Install: npm install docx Full API: docx.js.org

Top-level imports

const {
  Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
  ImageRun, Header, Footer, AlignmentType, PageOrientation,
  LevelFormat, ExternalHyperlink, InternalHyperlink, Bookmark,
  FootnoteReferenceRun, TabStopType, TabStopPosition,
  PositionalTab, PositionalTabAlignment, PositionalTabRelativeTo,
  PositionalTabLeader, Column, SectionType, TableOfContents,
  HeadingLevel, BorderStyle, WidthType, ShadingType,
  VerticalAlign, PageNumber, PageBreak, NumberFormat,
  LineNumberRestartFormat
} = require('docx');

Key enumerations

TextRun options

new TextRun({
  text: "Hello",
  bold: true,
  italics: true,
  underline: {},             // {} = single underline
  color: "FF0000",           // Hex, no "#"
  size: 24,                  // Half-points (24 = 12pt)
  font: "Arial",
  highlight: "yellow",       // yellow, green, cyan, magenta, blue, red, darkBlue, etc.
  strike: true,
  superScript: true,
  subScript: true,
  smallCaps: true,
  allCaps: true,
  break: 1,                  // Line breaks after run
  children: [PageNumber.CURRENT]  // For page numbers
})

Paragraph options

new Paragraph({
  children: [...],
  heading: HeadingLevel.HEADING_1,
  alignment: AlignmentType.CENTER,
  style: "MyStyle",
  spacing: { before: 240, after: 240, line: 276, lineRule: "auto" },
  indent: { left: 720, hanging: 360, firstLine: 720 },
  border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } },
  numbering: { reference: "bullets", level: 0 },
  pageBreakBefore: true,
  keepNext: true,
  keepLines: true,
  outlineLevel: 0,           // Required for TOC (0=H1, 1=H2, …)
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

ImageRun options

new ImageRun({
  type: "png",               // REQUIRED: png, jpg, jpeg, gif, bmp, svg
  data: fs.readFileSync("image.png"),
  transformation: { width: 200, height: 150 },
  floating: {                // Floating image (wrap text around)
    horizontalPosition: { offset: 1014400 },
    verticalPosition: { offset: 1014400 },
    wrap: { type: "square", side: "bothSides" },
  },
  altText: { title: "Title", description: "Desc", name: "Name" },
})

Section properties

{
  properties: {
    type: SectionType.NEXT_PAGE,   // CONTINUOUS, NEXT_PAGE, NEXT_COLUMN, EVEN_PAGE, ODD_PAGE
    page: {
      size: { width: 12240, height: 15840, orientation: PageOrientation.PORTRAIT },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440, gutter: 0 },
      pageNumbers: { start: 1, formatType: NumberFormat.DECIMAL },
    },
    column: {
      count: 2,
      space: 720,
      equalWidth: true,
      separate: true,
    },
    lineNumbers: { countBy: 1, restart: LineNumberRestartFormat.NEW_PAGE, start: 1 },
  },
  headers: { default: new Header({...}), first: new Header({...}), even: new Header({...}) },
  footers: { default: new Footer({...}) },
  children: [...],
}

Unit conversions

See Also

• $raw-document — specification-level reference (OOXML/ODF schemas, namespace tables, package structure deep-dives, cross-format mapping). Use when XML Reference above is insufficient or when schema validation, format recovery, or interoperability research is required.