# docx > Create, read, edit, and manipulate Word documents (.docx) with formatting, tables, images, headers, footers, tracked changes, and comments. - Skill: `memento-teams/docx` (Agent Skill, multi-file: 55 files) - Install (CLI): `npx skillmds add memento-teams/docx` - Raw SKILL.md: https://api.skillmd.com/api/skills/memento-teams/docx/raw - Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing, Office Documents - Tags: Document Generation, Docx, Libreoffice, Pandoc, Python Docx, Word, Xml - License: Proprietary. LICENSE.txt has complete terms - Author: Memento Teams (https://skillmd.com/u/memento-teams) - Updated: 2026-07-06 - Page: https://skillmd.com/skills/memento-teams/docx --- # DOCX creation, editing, and analysis ## Overview A .docx file is a ZIP archive containing XML files. ## Quick Reference | Task | Approach | |------|----------| | Read/analyze content | `pandoc` 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: ```bash python scripts/office/soffice.py --headless --convert-to docx document.doc ``` ### Reading Content ```bash # Text extraction with tracked changes pandoc --track-changes=all document.docx -o output.md # Raw XML access python scripts/office/unpack.py document.docx unpacked/ ``` ### Converting to Images ```bash python scripts/office/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): ```bash python scripts/accept_changes.py input.docx output.docx ``` --- ## Creating New Documents Use `python-docx` to create .docx files (auto-installed, no extra setup needed). ### Basic Document ```python from docx import Document from docx.shared import Pt, Inches, Cm, RGBColor from docx.enum.text import WD_ALIGN_PARAGRAPH doc = Document() # Set default font style = doc.styles['Normal'] font = style.font font.name = 'Arial' font.size = Pt(11) # Add content doc.add_heading('Document Title', level=0) doc.add_paragraph('This is a paragraph of text.') doc.add_heading('Section 1', level=1) doc.add_paragraph('Section content here.') doc.save('output.docx') ``` ### Paragraphs & Text Formatting ```python from docx.shared import Pt, RGBColor # Bold, italic, underline p = doc.add_paragraph() run = p.add_run('Bold text') run.bold = True run = p.add_run(' and ') run = p.add_run('italic text') run.italic = True # Font color and size run = p.add_run('Colored text') run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00) # Red run.font.size = Pt(14) # Alignment p.alignment = WD_ALIGN_PARAGRAPH.CENTER ``` ### Lists ```python # Bullet list doc.add_paragraph('First item', style='List Bullet') doc.add_paragraph('Second item', style='List Bullet') # Numbered list doc.add_paragraph('Step one', style='List Number') doc.add_paragraph('Step two', style='List Number') ``` ### Tables ```python from docx.shared import Inches, Pt, RGBColor from docx.oxml.ns import qn table = doc.add_table(rows=3, cols=3, style='Table Grid') # Header row header = table.rows[0] for i, text in enumerate(['Name', 'Role', 'Email']): cell = header.cells[i] cell.text = text # Bold header for paragraph in cell.paragraphs: for run in paragraph.runs: run.bold = True # Data rows data = [['Alice', 'Engineer', 'alice@example.com'], ['Bob', 'Designer', 'bob@example.com']] for i, row_data in enumerate(data): for j, text in enumerate(row_data): table.rows[i+1].cells[j].text = text # Set column widths for row in table.rows: row.cells[0].width = Inches(2) row.cells[1].width = Inches(2) row.cells[2].width = Inches(3) ``` ### Images ```python doc.add_picture('image.png', width=Inches(4)) # Centered image paragraph = doc.paragraphs[-1] paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER ``` ### Headers & Footers ```python from docx.shared import Pt section = doc.sections[0] # Header header = section.header header_para = header.paragraphs[0] header_para.text = 'Company Name' header_para.alignment = WD_ALIGN_PARAGRAPH.RIGHT # Footer with page numbers footer = section.footer footer_para = footer.paragraphs[0] footer_para.alignment = WD_ALIGN_PARAGRAPH.CENTER # Add page number field run = footer_para.add_run() fldChar = OxmlElement('w:fldChar') fldChar.set(qn('w:fldCharType'), 'begin') run._r.append(fldChar) run2 = footer_para.add_run() instrText = OxmlElement('w:instrText') instrText.text = ' PAGE ' run2._r.append(instrText) run3 = footer_para.add_run() fldChar2 = OxmlElement('w:fldChar') fldChar2.set(qn('w:fldCharType'), 'end') run3._r.append(fldChar2) ``` ### Page Setup ```python from docx.shared import Inches, Cm from docx.enum.section import WD_ORIENT section = doc.sections[0] # US Letter size section.page_width = Inches(8.5) section.page_height = Inches(11) # Margins section.top_margin = Inches(1) section.bottom_margin = Inches(1) section.left_margin = Inches(1) section.right_margin = Inches(1) # Landscape section.orientation = WD_ORIENT.LANDSCAPE section.page_width, section.page_height = section.page_height, section.page_width ``` ### Advanced: Creating with docx-js (requires Node.js) For advanced features like Table of Contents with auto-generation, complex numbering, or features not supported by python-docx, use docx-js: ```bash npm install -g docx # One-time setup ``` ```javascript const { Document, Packer, Paragraph, TextRun, HeadingLevel, TableOfContents } = require('docx'); const doc = new Document({ sections: [{ properties: { page: { size: { width: 12240, height: 15840 }, // US Letter in DXA margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } }, children: [ new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" }), new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] }), ] }] }); ``` ### Validation After creating the file, validate it. If validation fails, unpack, fix the XML, and repack. ```bash python scripts/office/validate.py doc.docx ``` --- ## Editing Existing Documents **Follow all 3 steps in order.** ### Step 1: Unpack ```bash 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: ```xml Here’s a quote: “Hello” ``` | Entity | Character | |--------|-----------| | `‘` | ‘ (left single) | | `’` | ’ (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): ```bash 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 ```bash 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 `` with whitespace **Auto-repair won't fix:** - Malformed XML, invalid element nesting, missing relationships, schema violations ### Common Pitfalls - **Replace entire `` elements**: When adding tracked changes, replace the whole `...` block with `......` as siblings. Don't inject tracked change tags inside a run. - **Preserve `` formatting**: Copy the original run's `` block into your tracked change runs to maintain bold, font size, etc. --- ## XML Reference ### Schema Compliance - **Element order in ``**: ``, ``, ``, ``, ``, `` last - **Whitespace**: Add `xml:space="preserve"` to `` with leading/trailing spaces - **RSIDs**: Must be 8-digit hex (e.g., `00AB1234`) ### Tracked Changes **Insertion:** ```xml inserted text ``` **Deletion:** ```xml deleted text ``` **Inside ``**: Use `` instead of ``, and `` instead of ``. **Minimal edits** - only mark what changes: ```xml The term is 30 60 days. ``` **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 `` inside ``: ```xml ... Entire paragraph content being deleted... ``` Without the `` in ``, accepting changes leaves an empty paragraph/list item. **Rejecting another author's insertion** - nest deletion inside their insertion: ```xml their inserted text ``` **Restoring another author's deletion** - add insertion after (don't modify their deletion): ```xml deleted text deleted text ``` ### 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: `` and `` are siblings of ``, never inside ``.** ```xml deleted more text text ``` ### Images 1. Add image file to `word/media/` 2. Add relationship to `word/_rels/document.xml.rels`: ```xml ``` 3. Add content type to `[Content_Types].xml`: ```xml ``` 4. Reference in document.xml: ```xml ``` --- ## Dependencies **Auto-installed (via metadata.dependencies):** - **python-docx**: Creating and editing documents (default) - **lxml**: XML processing - **defusedxml**: Secure XML parsing **Manual install (for advanced features):** - **docx (npm)**: `npm install -g docx` — advanced document creation with TOC support - **pandoc**: Text extraction — `brew install pandoc` (macOS) / `apt install pandoc` (Linux) - **LibreOffice**: PDF conversion, accepting tracked changes — `brew install --cask libreoffice` (macOS) / `apt install libreoffice` (Linux) - **Poppler**: `pdftoppm` for images — `brew install poppler` (macOS) / `apt install poppler-utils` (Linux)