docx_list
Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:“block”, nodeType:“listItem”, nodeId:“<id>”}. Exceptions: “create” and “attach” operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via docx_get_content({action:“blocks”}): pick listItem blocks for most actions, paragraph blocks for create/attach. CREATE & CONVERT: • “create”: make a NEW list from paragraphs. Two modes: mode:“empty” with at:{kind:“block”, nodeType:“paragraph”, nodeId} converts a single paragraph; mode:“fromParagraphs” with target:{from:{…paragraph block address}, to:{…paragraph block address}} converts a range: ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset (“disc”|“circle”|“square”|“dash” for bullets; “decimal”|“decimalParenthesis”|“lowerLetter”|“upperLetter”|“lowerRoman”|“upperRoman” for ordered) or a custom style. Use “create” to start a fresh list: NOT to extend an existing one (use “attach” for that). • “attach”: add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:“block”, nodeType:“listItem”, nodeId:“<any item in destination list>”} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see “join” below). • “set_type”: convert an existing list between ordered and bullet. Pass target:{listItem} + kind:“ordered” or “bullet”. Adjacent compatible sequences are merged automatically to preserve continuous numbering. • “detach”: convert a list item back to a plain paragraph. Pass target:{listItem}. ITEMS & NESTING: • “insert”: add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:“before”|“after” + optional text. Use this (NOT docx_create) to add items to an existing list. • “indent” / “outdent”: bump the target item’s nesting level by one (0-8 range). Pass target:{listItem}. • “set_level”: jump the target item to an explicit level. Pass target:{listItem} + level:0..8. NUMBERING (ordered lists): • “set_value”: restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence. • “continue_previous”: make the target’s sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists. SEQUENCE SHAPE (merge / split): • “merge”: merge the target’s sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:“withPrevious” or “withNext”. Absorbed items adopt the absorbing sequence’s numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously. • “split”: split the target’s sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.
Parameters
string, enum: 'attach' | 'continue_previous' | 'create' | 'detach' | 'indent' | 'insert' | 'merge' | 'outdent' | 'set_level' | 'set_type' | 'set_value' | 'split'
required
The action to perform. One of: attach, continue_previous, create, detach, indent, insert, merge, outdent, set_level, set_type, set_value, split.
boolean
Bypass confirmation checks.
string, enum: 'direct' | 'tracked'
Edit mode: “direct” applies changes immediately, “tracked” records as suggestions.
boolean
Preview the result without applying changes.
object
The target list item. For ‘insert’: the item to insert relative to. For ‘create’ with mode ‘fromParagraphs’: use nodeType ‘paragraph’ instead. Format: {kind:‘block’, nodeType:‘listItem’, nodeId:‘<id>’}. Required for actions ‘insert’, ‘attach’, ‘detach’, ‘indent’, ‘outdent’, ‘merge’, ‘split’, ‘set_level’, ‘set_value’, ‘continue_previous’, ‘set_type’.
string, enum: 'before' | 'after'
Required. Insert position relative to target: ‘before’ or ‘after’. Required for action ‘insert’.
string
Text content for the new list item. Only for action ‘insert’. Omit for other actions.
object
Operation input as JSON object.
string
Node ID of the target list item.
string, enum: 'empty' | 'fromParagraphs'
Required. ‘fromParagraphs’ converts existing paragraphs into list items: each paragraph becomes one item, so create one paragraph per item first. ‘empty’ creates a new empty list at ‘at’. Required for action ‘create’.
object
Required when mode is ‘empty’. The paragraph to create the list at. Format: {kind:‘block’, nodeType:‘paragraph’, nodeId:‘<id>’}. Only for action ‘create’. Omit for other actions.
string, enum: 'ordered' | 'bullet'
List type: ‘bullet’ for bullet points, ‘ordered’ for numbered lists. Required for action ‘set_type’.
number
List nesting level (0-8). 0 is the top level. Required for action ‘set_level’.
string, enum: 'decimal' | 'decimalParenthesis' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman' | 'disc' | 'circle' | 'square' | 'dash'
Predefined list style preset. Overrides ‘kind’ with a specific numbering or bullet format. Only for action ‘create’. Omit for other actions.
object
Only for action ‘create’. Omit for other actions.
Only for action ‘create’. Omit for other actions.
object
Required for action ‘attach’.
string, enum: 'withPrevious' | 'withNext'
Required for action ‘merge’.
boolean
Only for action ‘split’. Omit for other actions.
object
Required for action ‘set_value’.
string, enum: 'preserve' | 'none'
Numbering continuity: ‘preserve’ keeps numbering; ‘none’ restarts. Only for action ‘set_type’. Omit for other actions.
string
required
The HERO documentId of the docx to target.