docx

Files (32)

• SKILL.md
• editing.md
• __init__.py · scripts/
• accept_changes.py · scripts/
• comment.py · scripts/
• convert_doc.py · scripts/
• delete_sections.py · scripts/
• docx_patch.py · scripts/
• inspect_doc.py · scripts/
• inspect_headers.py · scripts/
• inspect_tables.py · scripts/
• list_sections.py · scripts/
• __init__.py · scripts/office/helpers/
• merge_runs.py · scripts/office/helpers/
• simplify_redlines.py · scripts/office/helpers/
• pack.py · scripts/office/
• soffice.py · scripts/office/
• unpack.py · scripts/office/
• validate.py · scripts/office/
• __init__.py · scripts/office/validators/
• base.py · scripts/office/validators/
• docx.py · scripts/office/validators/
• pptx.py · scripts/office/validators/
• redlining.py · scripts/office/validators/
• render_doc.py · scripts/
• replace_field.py · scripts/
• replace_text.py · scripts/
• comments.xml · scripts/templates/
• commentsExtended.xml · scripts/templates/
• commentsExtensible.xml · scripts/templates/
• commentsIds.xml · scripts/templates/
• people.xml · scripts/templates/

SKILL.md (first lines)

# DOCX creation, editing, and analysis

## Overview

A .docx file is a ZIP archive containing XML files. A .dotx file is a Word template — structurally identical to .docx.

## Quick Reference

| Task | Guide |
|------|-------|
| Edit or fill a template | Read [editing.md](editing.md) — **read this first when a template is attached** |
| Create from scratch | Read below (Creating New Documents) |
| Read/analyze content | `pandoc` or unpack for raw XML |

---

## When Given a Template — Read editing.md

**If a .docx or .dotx template is attached, you MUST read [editing.md](editing.md) before doing anything.** It contains the full workflow, all scripts, and pitfalls.

Key points:
- **Edit the template directly** — unpack, use scripts to replace text, repack
- **Never create from scratch** when a template exists
- **Never edit XML directly** — use `replace_text.py`, `replace_field.py`, `delete_sections.py`
- **.dotx files work the same as .docx** — `unpack.py` handles both

---

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

Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`

### Setup
```javascript
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 } = 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.
```bash
python scripts/office/validate.py doc.docx
```

### Page Size

```javascript
// 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):**

| 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:
```javascript
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

From Matrixx0070/xclaw, MIT.

More from Matrixx0070/xclaw