Open a .docx file for reading and editing.

Unpacks the DOCX archive, parses all XML parts, and caches them in memory. Only one document can be open at a time; opening a new one closes the previous.

Args: path: Absolute path to the .docx file.

Close the current document and clean up temporary files.

Create a new blank .docx document (or from a .dotx template).

The document is automatically opened for editing after creation. Use save_document to save changes, or start editing immediately with insert_text, add_table, etc.

Args: output_path: Path for the new .docx file. template_path: Optional path to a .dotx template file.

Create a new .docx document from markdown content.

Supports full GitHub-Flavored Markdown: headings, bold/italic/strikethrough, links, images, bullet/numbered/nested lists, code blocks, blockquotes, tables, footnotes, and task lists. Smart typography (curly quotes, em/en dashes, ellipses) is applied automatically.

Provide exactly one of md_path or markdown. The document is automatically opened for editing after creation.

Args: output_path: Path for the new .docx file. md_path: Path to a .md file. Mutually exclusive with markdown. markdown: Raw markdown text. Mutually exclusive with md_path. template_path: Optional path to a .dotx template file.

Get overview stats: paragraph count, headings, footnotes, comments, images.

Get the document heading structure with levels, text, and paraIds.

Returns a list of headings in document order, each with:

• level (1-9)

• text (heading content)

• style (e.g., "Heading1")

• paraId (unique paragraph identifier for targeting edits)

Search for text across the document body, footnotes, and comments.

Args: query: Text to search for (case-insensitive), or a regex pattern. regex: If true, treat query as a Python regular expression.

Returns matching paragraphs with their paraId, source part, and context.

Get the full text and style of a specific paragraph by its paraId.

Args: para_id: The 8-character hex paraId (e.g., "1A2B3C4D").

Get all tables with row/column counts and cell text content.

Insert a new table after a paragraph with tracked insertion.

Args: para_id: paraId of the paragraph to insert after. rows: Number of rows. cols: Number of columns. author: Author name for the revision.

Modify a table cell with tracked changes (delete old, insert new).

Args: table_idx: Table index (0-based). row: Row index (0-based). col: Column index (0-based). text: New cell text. author: Author name for the revision.

Add a row to a table with tracked insertion.

Args: table_idx: Table index (0-based). row_idx: Insert at this row index. -1 = append at end. cells: Cell text content. Empty = empty cells. author: Author name for the revision.

Delete a table row with tracked changes.

Args: table_idx: Table index (0-based). row_idx: Row index to delete (0-based). author: Author name for the revision.

Apply list formatting to paragraphs (bullet or numbered).

Creates numbering definitions and sets w:numPr on each target paragraph.

Args: para_ids: List of paraIds to format as list items. style: "bullet" or "numbered".

Get all defined styles with ID, name, type, and base style.

Get all headers and footers with their text content.

Edit text in a header or footer with tracked changes.

Args: location: "header" or "footer" (matches first found). old_text: Text to find and replace. new_text: Replacement text. author: Author name for the revision.

Get core document properties (title, creator, subject, dates, revision).

Set core document properties.

Args: title: Document title. Empty = unchanged. creator: Document author/creator. Empty = unchanged. subject: Document subject. Empty = unchanged. description: Document description. Empty = unchanged.

Get all embedded images with rId, filename, content type, and dimensions.

Insert an image into the document after a paragraph.

Args: para_id: paraId of the paragraph to insert after. image_path: Absolute path to the image file. width_emu: Image width in EMUs (914400 = 1 inch). height_emu: Image height in EMUs.

Get all endnotes with their ID and text content.

Add an endnote to a paragraph.

Creates the endnote definition in endnotes.xml and adds a superscript reference in the target paragraph.

Args: para_id: paraId of the paragraph to attach the endnote to. text: Endnote text content.

Cross-reference endnote IDs between document.xml and endnotes.xml.

Checks that every endnote reference has a matching definition, and flags orphaned definitions with no reference.

List all footnotes with their ID and text content.

Add a footnote to a paragraph.

Creates the footnote definition in footnotes.xml and adds a superscript reference number at the end of the target paragraph.

Args: para_id: paraId of the paragraph to attach the footnote to. text: Footnote text content.

Cross-reference footnote IDs between document.xml and footnotes.xml.

Checks that every footnote reference in the document body has a matching definition, and flags orphaned definitions with no reference.

Insert a page break after a paragraph.

Creates a new paragraph containing a page break element.

Args: para_id: paraId of the paragraph to insert after.

Add a section break at a paragraph.

Inserts a section properties element in the paragraph, marking it as the last paragraph of its section.

Args: para_id: paraId of the paragraph to place the section break on. break_type: "nextPage", "continuous", "evenPage", or "oddPage".

Modify section properties (page size, orientation, margins).

Args: para_id: paraId of paragraph with section break. Empty = body section. width: Page width in DXA (twips). 12240 = 8.5 inches. height: Page height in DXA. 15840 = 11 inches. orientation: "portrait" or "landscape". Empty = unchanged. margin_top: Top margin in DXA. 0 = unchanged. margin_bottom: Bottom margin in DXA. 0 = unchanged. margin_left: Left margin in DXA. 0 = unchanged. margin_right: Right margin in DXA. 0 = unchanged.

Add a cross-reference link from one paragraph to another.

Creates a bookmark at the target (if none exists) and inserts a hyperlink in the source paragraph with the given display text.

Args: source_para_id: paraId of the paragraph where the link appears. target_para_id: paraId of the paragraph being referenced. text: Display text for the cross-reference link.

Set document protection in settings.xml.

Args: edit: Protection type — "trackedChanges", "comments", "readOnly", "forms", or "none" (removes protection). password: Optional password (hashed with SHA-512). Empty = no password.

Merge another DOCX document's content into the current document.

Appends body paragraphs and tables from the source. ParaIds are automatically remapped to avoid collisions.

Args: source_path: Absolute path to the DOCX file to merge in.

Check paraId uniqueness across all document parts.

ParaIds must be unique across document.xml, footnotes.xml, headers, footers, and comments. They must also be valid 8-digit hex values < 0x80000000.

Remove VML watermarks (e.g., DRAFT) from all document headers.

Detects and removes <v:shape> elements with <v:textpath> inside header XML files — the standard pattern for Word watermarks.

Run a comprehensive structural audit of the document.

Checks:

• Footnote cross-references (references vs definitions)

• ParaId uniqueness and range validity

• Heading level continuity (no skips like H2 -> H4)

• Bookmark pairing (start/end matching)

• Relationship targets (all referenced files exist)

• Image references (all embedded images exist)

• Residual artifacts (DRAFT, TODO, FIXME markers)

Returns a detailed report with an overall valid/invalid status.

Insert text with Word track-changes markup (appears as a green underlined insertion in Word).

Args: para_id: paraId of the target paragraph. text: Text to insert. position: Where to insert — "start", "end", or a substring to insert after. author: Author name for the revision (shown in Word's review pane).

Mark text as deleted with Word track-changes markup (appears as red strikethrough in Word).

Finds the exact text within the paragraph and wraps it in deletion markup. The text must exist within a single run (formatting span).

Args: para_id: paraId of the target paragraph. text: Exact text to mark as deleted. author: Author name for the revision.

Accept tracked changes — keep insertions, remove deletions.

Args: author: If set, only accept changes by this author. Empty = all changes.

Reject tracked changes — remove insertions, restore deleted text.

Args: author: If set, only reject changes by this author. Empty = all changes.

Apply character formatting to text with tracked-change markup.

Finds the text within the paragraph, splits the run if needed, and applies formatting with rPrChange so it appears as a format revision in Word.

Args: para_id: paraId of the target paragraph. text: Exact text to format. bold: Apply bold formatting. italic: Apply italic formatting. underline: Underline style (e.g., "single", "double"). Empty = no underline. color: Font color as hex (e.g., "FF0000"). Empty = no color change. author: Author name for the revision.

List all comments with their ID, author, date, and text.

Add a comment anchored to a paragraph.

Creates the comment in comments.xml and adds range markers (commentRangeStart/End) around the paragraph content.

Args: para_id: paraId of the paragraph to comment on. text: Comment text. author: Author name (shown in Word's comment sidebar).

Reply to an existing comment (creates a threaded reply).

Args: parent_id: ID of the comment to reply to. text: Reply text. author: Author name.

Save all changes back to a .docx file.

Serializes modified XML parts and repacks into a DOCX archive.

Args: output_path: Path for the output file. If empty, overwrites the original.