raktim-mondol/dsh-researchcraft/docx-editor-zotero

docx-editor-zotero

Overview

Editing a Word document that contains Zotero citations with ordinary XML surgery (or by hand) easily orphans citation field codes or breaks the bibliography. This skill wraps python-docx-level .docx edits — deleting paragraphs, reordering paragraphs, bulk text replacement — with citation tracking so every Zotero field code, in-text citation, and bibliography entry survives the edit, and produces a JSON audit log of exactly what changed.

Zero external dependencies — pure Python 3.10+ standard library (xml.etree.ElementTree, zipfile, json). Run it with uv run python per this plugin's Python convention; no uv add needed.

When to use this skill

Reach for this instead of hand-editing .docx XML or reaching for python-docx directly whenever the document being edited has Zotero citations and the task is: removing sections/paragraphs, reordering them, or bulk text replacement (e.g. terminology changes across a manuscript) — not for documents without Zotero fields, where the docx skill's normal tooling is sufficient.

Basic workflow

1. Load the input .docx with WordEditor (scripts/word_editor.py).
2. It extracts every Zotero citation and its position before any edit.
3. Apply structural modifications in this order: delete → reorder → replace.
4. It recalculates endnote/citation IDs and flags orphaned citations.
5. Validate document integrity, then save the edited .docx plus a

*_log.json audit trail (timestamps, paragraphs deleted, citations orphaned/preserved, text replacements, validation results).

from word_editor import WordEditor
editor = WordEditor("input.docx")
editor.delete_paragraphs([1, 3, 5])
editor.move_paragraph(2, 0)
editor.replace_text("HSG", "Tkk")
editor.save("output.docx")

Run it from inside scripts/ (or add that directory to sys.path) since word_editor.py imports zotero_docx_preserver.py as a sibling module — both ship together in scripts/.

Notes

• After editing, the user may need to refresh Zotero fields in Word via the

Zotero menu (Word doesn't always auto-refresh field display after an out-of-band XML edit).

• Handles documents containing tables and complex nested elements.
• The original file is never modified in place — always writes a new output

path, so edits are trivially reversible.

• See references/EXAMPLES.md for worked examples of each operation

(delete, reorder, replace, and combinations) with expected output.