> ## Documentation Index
> Fetch the complete documentation index at: https://developers.myhero.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Docx edit

> The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block…

`docx_edit`

The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use docx\_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from **text**, italic from *text*, and numbered/bullet lists. Position markdown inserts with "target" (a BlockNodeAddress like \{kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE docx\_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. Use scope: "block" so formatting covers the entire paragraph. Copy the exact property values from the existing get\_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. Also supports replace, delete, and undo/redo. For replace and delete, pass a "ref" from docx\_search or docx\_get\_content blocks. A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. For multi-step redlines or whole-clause rewrites, prefer docx\_mutations with where:\{by:"block", nodeType, nodeId} from docx\_get\_content action "blocks" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use docx\_mutations instead. Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes (not supported for markdown/html inserts). Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting.

## Parameters

**action** `string, enum: 'delete' | 'insert' | 'redo' | 'replace' | 'undo'` *required*

The action to perform. One of: delete, insert, redo, replace, undo.

**force** `boolean`

Bypass confirmation checks.

**changeMode** `string, enum: 'direct' | 'tracked'`

Edit mode: "direct" applies changes immediately, "tracked" records as suggestions.

**dryRun** `boolean`

Preview the result without applying changes.

**target**

Target address. For inline/set\_style: prefer 'ref' from docx\_search, or use \{kind:'selection', start:\{kind:'text', blockId, offset}, end:\{kind:'text', blockId, offset}}. For paragraph actions (set\_alignment, set\_indentation, set\_spacing, set\_direction, set\_flow\_options): use \{kind:'block', nodeType:'paragraph'|'heading'|'listItem', nodeId:'\<nodeId from blocks list>'}.

**value** `string`

Text content to insert. Only for action 'insert'. Omit for other actions.

**type** `string, enum: 'text' | 'markdown' | 'html'`

Content format: 'text' (default), 'markdown', or 'html'. Only for action 'insert'. Omit for other actions.

**ref** `string`

Handle ref from docx\_search result (pass handle.ref value directly). Preferred over building a target object.

**content**

Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions.

**placement** `string, enum: 'before' | 'after' | 'insideStart' | 'insideEnd'`

Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'. Only for action 'insert'. Omit for other actions.

**nestingPolicy** `object`

Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions.

**text** `string`

Replacement text content. Only for action 'replace'. Omit for other actions.

**behavior** `string, enum: 'selection' | 'exact'`

Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions.

**documentId** `string` *required*

The HERO documentId of the docx to target.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.