Skip to content

word numbering

Jump to bottom
zmworm edited this page Apr 29, 2026 · 3 revisions

Word: Numbering

Multi-level lists (numbered/bulleted) live under the /numbering part. OfficeCLI exposes the full Word numbering model via three element types:

  • abstractNum — a numbering template (per-level format, text, indent, fonts)
  • num — a numbering instance that references an abstractNum (with optional per-level overrides)
  • lvl — an individual level inside an abstractNum

A paragraph picks up numbering by setting numId (referencing a num) and ilvl (the level).

Path:

  • /numbering/abstractNum[@id=N] — numbering template
  • /numbering/abstractNum[@id=N]/level[L] — single level (L = 0..8)
  • /numbering/num[@id=N] — numbering instance

Positional indices /numbering/abstractNum[N] and /numbering/num[N] are accepted on Set and normalized to the canonical [@id=K] form.

abstractNum — add a numbering template

officecli add report.docx /numbering --type abstractNum [--prop ...]

Top-level properties

Property Description
name Template name (returned in Get readback)
type singleLevel, multilevel, hybridMultilevel, bullet
styleLink Style link target
numStyleLink NumStyle link target

Per-level dotted properties (level0..level8.<prop>)

Sub-property Description
format decimal, lowerLetter, upperLetter, lowerRoman, upperRoman, bullet, none
text Level format string (e.g. %1., %1.%2., •)
start Starting number
indent Left indent (twips or unit-qualified: 0.5in, 1cm)
hanging Hanging indent
justification left, center, right
suff Suffix character: tab, space, nothing
font Font family for the marker
size Marker font size (pt)
color Marker font color (hex)
bold Marker bold
italic Marker italic
lvlRestart Restart counter at this level
isLgl Legal-style numbering

Levels left unset cycle through decimal / lowerLetter / lowerRoman (or bullet glyphs for type=bullet) — same fallback as the high-level liststyle path.

Examples

# Multilevel template with custom level 0 + level 1
officecli add report.docx /numbering --type abstractNum --prop name="MyOutline" \
  --prop type=multilevel \
  --prop level0.format=decimal --prop "level0.text=%1." --prop level0.indent=0.5in \
  --prop level1.format=lowerLetter --prop "level1.text=%2)" --prop level1.indent=1in

# Bullet template
officecli add report.docx /numbering --type abstractNum \
  --prop type=bullet \
  --prop level0.font=Symbol --prop "level0.text=●" \
  --prop level1.font=Symbol --prop "level1.text=○"

num — add a numbering instance

officecli add report.docx /numbering --type num [--prop ...]

Three modes:

Mode Trigger Behavior
A auto-create No abstractNumId Auto-creates a matching abstractNum from format/text/indent/type props (same builder as --type abstractNum)
B reuse template abstractNumId=N References an existing abstractNum
C override starts start=N or startOverride.0..8=N Per-level start overrides

Examples

# Mode B: reuse existing template
officecli add report.docx /numbering --type num --prop abstractNumId=3

# Mode C: per-level start overrides
officecli add report.docx /numbering --type num \
  --prop abstractNumId=3 \
  --prop startOverride.0=5 --prop startOverride.1=1

# Mode A: auto-create template inline
officecli add report.docx /numbering --type num \
  --prop type=multilevel --prop level0.format=decimal

lvl — append/edit a single level

officecli add report.docx /numbering/abstractNum[@id=N] --type lvl --prop ilvl=L [--prop ...]
Property Required Description
ilvl yes Level index (0..8)
start no Starting number
format, text, indent, hanging, justification, suff, font, size, color, bold, italic, lvlRestart, isLgl no Same as per-level dotted props above

Set on /numbering/abstractNum[@id=N]/level[L] and /lvl[@ilvl=L] accept the same properties.

Style-borne numPr

add --type style and set /styles/X accept numId and ilvl directly:

officecli set report.docx /styles/Heading1 --prop numId=3 --prop ilvl=0

Paragraphs inheriting via pStyle then pick up numbering through ResolveNumPrFromStyle without their own numPr — the canonical Heading1..9 multi-level pattern in Word templates.

Validation

Rejection Error
Paragraph numId references a missing <w:num> Reference rejected at Set time (no zombie references)
--type style with numId=N where N has no <w:num> Rejected at add and set
Negative numId on paragraph Rejected
ilvl outside 0..8 on paragraph Set Clamped to range
Removing a num clears any paragraph numPr references that pointed at it Automatic cleanup

query

Selectors numbering, abstractNum, num are supported:

officecli query report.docx 'abstractNum'
officecli query report.docx 'num[@id=5]'

Get readback

/numbering/num[@id=N], /numbering/abstractNum[@id=N], and /numbering/abstractNum[@id=N]/level[L] return canonical Format dicts. abstractNum Get returns a Children list of all 9 levels.

officecli get report.docx '/numbering/abstractNum[@id=2]'
officecli get report.docx '/numbering/abstractNum[@id=2]/level[0]'
officecli get report.docx '/numbering/num[@id=5]'

Tab stops on paragraphs

Tab stops can be added to a paragraph or to a paragraph/table style:

officecli add report.docx /body/p[3] --type tab \
  --prop pos=720 --prop val=left --prop leader=dot

officecli add report.docx /styles/MyStyle --type tab --prop pos=2880 --prop val=right
Property Description
pos Tab position (twips or unit-qualified)
val Tab type: left, center, right, decimal, bar, clear, num
leader Leader: none, dot, hyphen, underscore, heavy, middleDot

Both val and leader are validated against an allowlist with friendly error messages.

See Also

Based on OfficeCLI v1.0.64

Clone this wiki locally