lightspeedwp/.github/docx

DOCX Skill (Read • Create • Edit • Redline • Comment)

Use this skill when you need to create or modify .docx files in this container environment and verify them visually.

Non-negotiable: render → inspect PNGs → iterate

You do not “know” a DOCX is satisfactory until you’ve rendered it and visually inspected page images. DOCX text extraction (or reading XML) will miss layout defects: clipping, overlap, missing glyphs, broken tables, spacing drift, and header/footer issues.

Shipping gate: before delivering any DOCX, you must:

• Run render_docx.py to produce page-<N>.png images (optionally also a PDF with --emit_pdf)
• Open the PNGs (100% zoom) and confirm every page is clean
• If anything looks off, fix the DOCX and re-render (repeat until flawless)

If rendering fails, fix rendering first (LibreOffice profile/HOME) rather than guessing.

Deliverable discipline: Rendered artifacts (PNGs and optional PDFs) are for internal QA only. Unless the user explicitly asks for intermediates, return only the requested final deliverable (e.g., when the task asks for a DOCX, deliver the DOCX — not page images or PDFs).

Quick start (common one-liners)

# 1) Render any DOCX to PNGs (visual QA)
python render_docx.py input.docx --output_dir out
 
# 2) Remove reviewer comments (finalization)
python scripts/comments_strip.py input.docx --out no_comments.docx
 
# 3) Accept tracked changes (finalization)
python scripts/accept_tracked_changes.py input.docx --mode accept --out accepted.docx
 
# 4) Accessibility audit (+ optional safe fixes)
python scripts/a11y_audit.py input.docx
python scripts/a11y_audit.py input.docx --out_json a11y_report.json
python scripts/a11y_audit.py input.docx --fix_image_alt from_filename --out a11y_fixed.docx
 
# 5) Redact sensitive text (layout-preserving by default)
python scripts/redact_docx.py input.docx redacted.docx --emails --phones

Package layout

This skill is organized for progressive discovery: start here, then jump into task- or OOXML-specific docs.

DOCS SKILL PACKAGE

Root:

• SKILL.md: short overview + routing
• manifest.txt: machine-readable list of files to download (one relative path per line)
• render_docx.py: canonical DOCX→PNG renderer (container-safe LO profile + writable HOME + verbose logs)

Tasks:

• tasks/read_review.md
• tasks/create_edit.md
• tasks/verify_render.md
• tasks/accessibility_a11y.md
• tasks/comments_manage.md
• tasks/protection_restrict_editing.md
• tasks/privacy_scrub_metadata.md
• tasks/multi_doc_merge.md
• tasks/style_lint_normalize.md
• tasks/forms_content_controls.md
• tasks/captions_crossrefs.md
• tasks/redaction_anonymization.md
• tasks/clean_tracked_changes.md
• tasks/compare_diff.md
• tasks/templates_style_packs.md
• tasks/watermarks_background.md
• tasks/footnotes_endnotes.md
• tasks/fixtures_edge_cases.md
• tasks/navigation_internal_links.md

OOXML:

• ooxml/tracked_changes.md
• ooxml/comments.md
• ooxml/hyperlinks_and_fields.md
• ooxml/rels_and_content_types.md

Troubleshooting:

• troubleshooting/libreoffice_headless.md
• troubleshooting/run_splitting.md

Scripts:

Core building blocks (importable helpers):

• scripts/docx_ooxml_patch.py — low-level OOXML patch helper (tracked changes, comments, hyperlinks, relationships). Other scripts reuse this.
• scripts/fields_materialize.py — materialize SEQ/REF field display text for deterministic headless rendering/QA.

High-leverage utilities (also importable, but commonly invoked as CLIs):

• render_docx.py — canonical DOCX → PNG renderer (optional PDF via --emit_pdf; do not deliver intermediates unless asked).
• scripts/render_and_diff.py — render + per-page image diff between two DOCXs.
• scripts/content_controls.py — list / wrap / fill Word content controls (SDTs) for forms/templates.
• scripts/captions_and_crossrefs.py — insert Caption paragraphs for tables/figures + optional bookmarks around caption numbers.
• scripts/insert_ref_fields.py — replace [[REF:bookmark]] markers with real REF fields (cross-references).
• scripts/internal_nav.py — add internal navigation links (static TOC + Top/Bottom + figN/tblN jump links).
• scripts/style_lint.py — report common formatting/style inconsistencies.
• scripts/style_normalize.py — conservative cleanup (clear run-level overrides; optional paragraph overrides).
• scripts/redact_docx.py — layout-preserving redaction/anonymization.
• scripts/privacy_scrub.py — remove personal metadata + rsid* attributes.
• scripts/set_protection.py — restrict editing (read-only / comments / forms).
• scripts/comments_extract.py — extract comments to JSON (text, author/date, resolved flag, anchored snippets).
• scripts/comments_strip.py — remove all comments (final-delivery mode).

Audits / conversions / niche helpers:

• scripts/fields_report.py, scripts/heading_audit.py, scripts/section_audit.py, scripts/images_audit.py, scripts/footnotes_report.py, scripts/watermark_audit_remove.py
• scripts/xlsx_to_docx_table.py, scripts/docx_table_to_csv.py
• scripts/insert_toc.py, scripts/insert_note.py, scripts/apply_template_styles.py, scripts/accept_tracked_changes.py, scripts/make_fixtures.py

v7 additions (stress-test helpers):

• scripts/watermark_add.py — add a detectable VML watermark object into an existing header.
• scripts/comments_add.py — add multiple comments (by paragraph substring match) and wire up comments.xml plumbing if needed.
• scripts/comments_apply_patch.py — append/replace comment text and mark/clear resolved state (w:done=1).
• scripts/add_tracked_replacements.py — generate tracked-change replacements (<w:del> + <w:ins>) in-place.
• scripts/a11y_audit.py — audit a11y issues; can also apply simple fixes via --fix_table_headers / --fix_image_alt.
• scripts/flatten_ref_fields.py — replace REF/PAGEREF field blocks with their cached visible text for deterministic rendering.

scripts/xlsx_to_docx_table.py also marks header rows as repeating headers (w:tblHeader) to improve a11y and multi-page tables.

Examples:

• examples/end_to_end_smoke_test.md

Note: manifest.txt is machine-readable and is used by download tooling. It must contain only relative file paths (one per line).

Coverage map (scripts ↔ task guides)

This is a quick index so you can jump from a helper script to the right task guide.

Layout & style

• style_lint.py, style_normalize.py → tasks/style_lint_normalize.md
• apply_template_styles.py → tasks/templates_style_packs.md
• section_audit.py → tasks/sections_layout.md
• heading_audit.py → tasks/headings_numbering.md

Figures / images

• images_audit.py, a11y_audit.py → tasks/images_figures.md, tasks/accessibility_a11y.md
• captions_and_crossrefs.py → tasks/captions_crossrefs.md

Tables / spreadsheets

• xlsx_to_docx_table.py → tasks/tables_spreadsheets.md
• docx_table_to_csv.py → tasks/tables_spreadsheets.md

Fields & references

• fields_report.py, fields_materialize.py → tasks/fields_update.md
• insert_ref_fields.py, flatten_ref_fields.py → tasks/fields_update.md, tasks/captions_crossrefs.md
• insert_toc.py → tasks/toc_workflow.md

Review lifecycle (comments / tracked changes)

• add_tracked_replacements.py, accept_tracked_changes.py → tasks/clean_tracked_changes.md
• comments_add.py, comments_extract.py, comments_apply_patch.py, comments_strip.py → tasks/comments_manage.md

Privacy / publishing

• privacy_scrub.py → tasks/privacy_scrub_metadata.md
• redact_docx.py → tasks/redaction_anonymization.md
• watermark_add.py, watermark_audit_remove.py → tasks/watermarks_background.md

Navigation & multi-doc assembly

• internal_nav.py → tasks/navigation_internal_links.md
• merge_docx_append.py → tasks/multi_doc_merge.md

Forms & protection

• content_controls.py → tasks/forms_content_controls.md
• set_protection.py → tasks/protection_restrict_editing.md

QA / regression

• render_and_diff.py, render_docx.py → tasks/compare_diff.md, tasks/verify_render.md
• make_fixtures.py → tasks/fixtures_edge_cases.md
• docx_ooxml_patch.py → used across guides for targeted patches

Skill folder contents

• tasks/ — task playbooks (what to do step-by-step)
• ooxml/ — advanced OOXML patches (tracked changes, comments, hyperlinks, fields)
• scripts/ — reusable helper scripts
• examples/ — small runnable examples

Default workflow (80/20)

Rule of thumb: every meaningful edit batch must end with a render + PNG review. No exceptions. "80/20" here means: follow the simplest workflow that covers most DOCX tasks reliably.

Golden path (don’t mix-and-match unless debugging):

1. Author/edit with `python-docx` (paragraphs, runs, styles, tables, headers/footers).
2. Render → inspect PNGs immediately (DOCX → PNGs). Treat this as your feedback loop.
3. Fix and repeat until the PNGs are visually perfect.
4. Only if needed: use OOXML patching for tracked changes, comments, hyperlinks, or fields.
5. Re-render and inspect again after any OOXML patch or layout-sensitive change.
6. Deliver only after the latest PNG review passes (all pages, 100% zoom).

Visual review (recommended)

Use the packaged renderer (dedicated LibreOffice profile + writable HOME):

python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out
# If debugging LibreOffice:
python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out --verbose
# Optional: also write <input_stem>.pdf to --output_dir (for debugging/archival):
python render_docx.py /mnt/data/input.docx --output_dir /mnt/data/out --emit_pdf

Then inspect the generated page-<N>.png files.

Success criteria (render + visual QA):

• PNGs exist for each page
• Page count matches expectations
• Inspect every page at 100% zoom (no “spot check” for final delivery)
• No clipping/overlap, no broken tables, no missing glyphs, no header/footer misplacement

Note: LibreOffice sometimes prints scary-looking stderr (e.g., error : Unknown IO error) even when output is correct. Treat the render as successful if the PNGs exist and look right (and if you used --emit_pdf, the PDF exists and is non-empty).

What rendering does and doesn’t validate

• Great for: layout correctness, fonts, spacing, tables, headers/footers, and whether tracked changes visually appear.
• Not reliable for: comments (often not rendered in headless PDF export). For comments, also do structural checks (comments.xml + anchors + rels + content-types).

Quality reminders

• Don’t ship visible defects (clipped/overlapping text, broken tables, unreadable glyphs).
• Don’t leak tool citation tokens into the DOCX (convert them to normal human citations).
• Prefer ASCII punctuation (avoid exotic Unicode hyphens/dashes that render inconsistently).

Where to go next