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.
Edit mode: “direct” applies changes immediately, “tracked” records as suggestions.
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’.
Required. Insert position relative to target: ‘before’ or ‘after’. Required for action ‘insert’.
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’.
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.
List type: ‘bullet’ for bullet points, ‘ordered’ for numbered lists. Required for action ‘set_type’.
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.
Numbering continuity: ‘preserve’ keeps numbering; ‘none’ restarts. Only for action ‘set_type’. Omit for other actions.