iofficeai--officecli/examples/word/paragraph-formatting.md

Paragraph Formatting Showcase

Exercises the docx paragraph property surface. Three files:

• paragraph-formatting.sh — builds the document with officecli (155 lines, ~55 commands).
• paragraph-formatting.docx — generated output, one paragraph per property group.
• paragraph-formatting.md — this file.

Regenerate

cd examples/word
bash paragraph-formatting.sh
# → paragraph-formatting.docx

Alignment

The four standard paragraph alignment values.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Left aligned (default)" --prop align=left
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Center aligned" --prop align=center
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Right aligned" --prop align=right
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Justified text stretched edge to edge..." --prop align=both

Features: align (left/center/right/both/distribute/thai/mediumKashida/highKashida/lowKashida)

Indentation

Left, right, first-line, and hanging indent — all accepting twips, cm, or in.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Left indent 1cm" --prop indent=1cm
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Right indent 2cm..." --prop rightIndent=2cm
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=First-line indent — only the first line is pushed in." \
  --prop firstLineIndent=1cm
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Hanging indent — first line hangs left." \
  --prop indent=1cm --prop hangingIndent=1cm

Features: indent (left indent; twips, cm, in, pt), rightIndent, firstLineIndent (positive → indent first line extra), hangingIndent (positive → all-but-first lines indented; combine with indent of equal value)

Spacing

Space before/after in points, and line spacing as a multiplier or fixed value.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Space before 18pt, after 6pt" \
  --prop spaceBefore=18pt --prop spaceAfter=6pt
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Line spacing 1.5x across a longer paragraph..." \
  --prop lineSpacing=1.5x

Features: spaceBefore (space above; accepts 18pt, 0.5cm, 360 twips), spaceAfter, lineSpacing (1.5x/150%/18pt/bare number; normalised via SpacingConverter)

Pagination Flags

Control how Word breaks pages around this paragraph.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=keepNext — stays with the following paragraph" \
  --prop keepNext=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=keepLines — lines stay together, never split across pages" \
  --prop keepLines=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=widowControl on" --prop widowControl=true

Features: keepNext (force this paragraph and the next onto the same page), keepLines (prevent page break within the paragraph), widowControl (prevent single-line orphans/widows)

Paragraph-Level Run Formatting

Properties set at the paragraph level apply to every run in the paragraph (equivalent to selecting all and formatting).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Whole paragraph bold + red + 13pt" \
  --prop bold=true --prop color=C00000 --prop size=13
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Whole paragraph italic + highlighted" \
  --prop italic=true --prop highlight=yellow

Features: bold, italic, color, size, highlight — when set on --type paragraph these become paragraph-level run defaults (w:pPr/w:rPr), not inline run properties.

Shading

Paragraph background fill color, with optional pattern.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Light gray paragraph shading" --prop shading.fill=D9D9D9
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Pale blue shading" --prop shading.fill=DDEBF7

Features: shading.fill (solid fill hex color; writer defaults w:shd/@val to clear), shd (shorthand alias for shading.fill), shading.val (pattern type: pct15/pct25/pct50/…), shading.color (pattern foreground color)

Paragraph-Mark Formatting (markRPr)

The paragraph mark (¶ pilcrow) has its own run properties, distinct from the paragraph's run defaults. This controls what formatting a newly typed run at the end of the paragraph inherits.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=The mark glyph is bold+red (distinct from run text)" \
  --prop markRPr.bold=true --prop markRPr.color=C00000

# Full markRPr set
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=mark: italic/strike/underline/size/highlight/fonts" \
  --prop markRPr.italic=true --prop markRPr.strike=true \
  --prop markRPr.underline=single --prop markRPr.size=14pt \
  --prop markRPr.highlight=yellow \
  --prop markRPr.font.latin=Georgia \
  --prop markRPr.font.ea=SimSun --prop markRPr.font.cs=Arial

Features: markRPr.bold, markRPr.italic, markRPr.strike, markRPr.underline, markRPr.size, markRPr.color, markRPr.highlight, markRPr.font.latin, markRPr.font.ea, markRPr.font.cs

Setting bold=true on a paragraph makes every run bold. Setting markRPr.bold=true formats only the ¶ mark — they are independent and both settable/gettable.

Outline Level

Assign a paragraph to the document outline (affects navigation pane, table of contents, heading styles).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Outline level 1 (shows in document map)" --prop outlineLvl=1

Features: outlineLvl (0–8; 0 = body text, 1–8 = heading levels; 9 = no outline level)

Paragraph Strike & Underline

Strike-through and underline can also be applied at the paragraph level (to all runs).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Whole paragraph struck out" --prop strike=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Underlined paragraph (red wave)" \
  --prop underline=wave --prop underline.color=#FF0000

Features: strike (paragraph-level single strikethrough), underline (paragraph-level underline style), underline.color (accepts leading # — stripped before storage)

Complex-Script (cs) Properties

Separate formatting for complex-script (bidirectional, Arabic, Hebrew) glyph runs.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=cs bold/italic/14pt + RTL" \
  --prop bold.cs=true --prop italic.cs=true \
  --prop size.cs=14pt --prop direction=rtl

Features: bold.cs, italic.cs, size.cs (complex-script weight/style/size), direction (rtl sets w:bidi on the paragraph)

Spacing & Pagination Extras

Additional spacing and pagination controls beyond the basic set.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=contextualSpacing (collapse between same-style paras)" \
  --prop contextualSpacing=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=lineSpacing 14pt, lineRule=atLeast" \
  --prop lineSpacing=14pt --prop lineRule=atLeast
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=pageBreakBefore" --prop pageBreakBefore=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=wordWrap off (break long URLs anywhere)" --prop wordWrap=false

Features: contextualSpacing (suppress space-before/after between paragraphs of the same style), lineRule (atLeast/exactly/auto), pageBreakBefore (force a page break before this paragraph), wordWrap (false = break at any character, not just word boundaries)

Chars-Based Indent

CJK-friendly indentation in 1/100-character units (avoids relying on absolute twip values).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=first-line 200 chars, hanging 100 chars" \
  --prop firstLineChars=200 --prop hangingChars=100

Features: firstLineChars (first-line indent in 1/100-char units; 200 = 2 characters), hangingChars

Fonts (Explicit & Theme)

Per-script font families and theme font slots.

# Shorthand — sets all scripts
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=font shorthand Times New Roman" \
  --prop font="Times New Roman"

# Explicit per-script
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=per-script latin/ea/cs" \
  --prop font.latin=Calibri --prop font.ea=SimSun --prop font.cs=Arial

# Theme references
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=theme fonts" \
  --prop font.asciiTheme=minorHAnsi --prop font.hAnsiTheme=minorHAnsi \
  --prop font.eaTheme=minorEastAsia --prop font.csTheme=minorBidi

Features: font (all-scripts shorthand), font.latin, font.ea, font.cs, font.asciiTheme (majorHAnsi/minorHAnsi), font.hAnsiTheme, font.eaTheme, font.csTheme

Styles

Apply a named paragraph style or a character style to all runs.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Paragraph style Heading1" --prop style=Heading1
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Character style on the run" --prop rStyle=Emphasis

Features: style (paragraph style ID; e.g. Heading1, Normal, ListBullet), rStyle (character style ID applied to the paragraph's default run properties)

Shading Variants

Different ways to express paragraph background shading.

# Shorthand alias
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=shd shorthand (yellow)" --prop shd=FFFF00

# Decomposed: pattern + fill color + pattern foreground color
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=pct15 pattern, blue fill, red pattern color" \
  --prop shading.val=pct15 --prop shading.fill=DDEBF7 --prop shading.color=C00000

Features: shd (shorthand alias for shading.fill), shading.val (pattern: clear/pct5/pct10/pct15/pct25/pct50/solid/…), shading.fill (fill color hex), shading.color (pattern foreground hex)

Tab Stops

Declare tab stop positions in twips.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Tabs at 720 and 1440 twips" --prop tabs=720,1440

Features: tabs (comma-separated list of tab positions in twips; 720 = 0.5in, 1440 = 1in)

Text Frame (framePr)

A framed paragraph floats in its own positioned box, with body text optionally wrapping around it. Dimensions use twips.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Framed paragraph — floats in a 3-inch box with text wrapping." \
  --prop framePr.w=4320 --prop framePr.h=720 --prop framePr.wrap=around \
  --prop framePr.hAnchor=margin --prop framePr.vAnchor=text \
  --prop framePr.hSpace=180 --prop framePr.vSpace=180

Features: framePr.w (frame width in twips; 4320 = 3in), framePr.h (height), framePr.wrap (around/notBeside/none/tight/through), framePr.hAnchor (margin/page/text), framePr.vAnchor, framePr.hSpace (horizontal clearance), framePr.vSpace

Paragraph Borders (pBdr)

Whole-box shorthand (border=) sets all four sides at once, accepting style, style;size;color, or style;size;color;space. Per-side keys (border.top, border.bottom, border.left, border.right) take the same value and can be mixed for a partial box (e.g. a rule above and below only).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Box border, all sides (single)" --prop border=single
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Red 1pt box (style;size;color)" \
  --prop "border=single;8;FF0000"
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Per-side: top + bottom only (rule above and below)" \
  --prop "border.top=single;8;0070C0" --prop "border.bottom=single;8;0070C0"

Features: border (whole-box paragraph border; format style or style;size;color or style;size;color;space; style values: single/double/thick/dotted/dashed/dotDash/…), border.top/border.bottom/border.left/border.right (per-side, same value format)

Vertical Text Alignment

Control how glyphs align vertically within the line box (distinct from cell vertical alignment).

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=textAlignment=center (glyphs centered on the line box)" \
  --prop textAlignment=center
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=textAlignment=top" --prop textAlignment=top

Features: textAlignment (top/center/baseline/bottom/auto)

EastAsian Typography

CJK line-breaking and spacing rules.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=kinsoku off — permit breaks at forbidden CJK chars" \
  --prop kinsoku=false
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=autoSpace off — no auto gap between CJK and Latin/digits" \
  --prop autoSpaceDE=false --prop autoSpaceDN=false
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=overflowPunct + topLinePunct on" \
  --prop overflowPunct=true --prop topLinePunct=true

Features: kinsoku (Japanese line-break constraint; false = allow breaks at forbidden positions), autoSpaceDE (auto spacing between CJK and Latin), autoSpaceDN (auto spacing between CJK and digits), overflowPunct (allow punctuation to hang outside margin), topLinePunct (compress leading punctuation to top of line)

Line & Indent Flags

Miscellaneous line-number, hyphenation, and indent behaviour toggles.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=suppressLineNumbers + suppressAutoHyphens" \
  --prop suppressLineNumbers=true --prop suppressAutoHyphens=true
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=mirrorIndents on, adjustRightInd off, snapToGrid off" \
  --prop mirrorIndents=true --prop adjustRightInd=false --prop snapToGrid=false

Features: suppressLineNumbers (exclude from line number count), suppressAutoHyphens (disable hyphenation), mirrorIndents (swap left/right indent on alternate pages for book layout), adjustRightInd (auto-adjust right indent for document grid), snapToGrid (snap paragraph to the document character grid)

Web / Textbox Hints

Layout hints for web view and textbox flow.

officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=divId (web division id) + textboxTightWrap=allLines" \
  --prop divId=123456 --prop textboxTightWrap=allLines

Features: divId (integer web-division ID for HTML round-trip), textboxTightWrap (none/allLines/firstAndLastLine/firstLineOnly/lastLineOnly)

List Numbering

Attach a paragraph to a list via a high-level style shorthand or direct numPr references.

# High-level shorthand
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Bulleted item" --prop listStyle=bullet
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Ordered item starting at 5" \
  --prop listStyle=ordered --prop start=5

# Direct numPr reference
officecli add paragraph-formatting.docx /body --type paragraph \
  --prop "text=Explicit numId=1 level 0" --prop numId=1 --prop numLevel=0

Features: listStyle (bullet/ordered — creates or reuses a numbering definition automatically), start (override starting counter for this instance), numId (direct reference to a w:num element by id), numLevel (alias: ilvl; 0-based indent level)

Complete Feature Coverage

Feature	Section
align (left/center/right/both)	Alignment
indent, rightIndent, firstLineIndent, hangingIndent	Indentation
spaceBefore, spaceAfter, lineSpacing	Spacing
keepNext, keepLines, widowControl	Pagination Flags
bold, italic, color, size, highlight (paragraph-level)	Paragraph-Level Run Formatting
shading.fill, shd	Shading
markRPr.* (full set)	Paragraph-Mark Formatting
outlineLvl	Outline Level
strike, underline, underline.color (paragraph-level)	Paragraph Strike & Underline
bold.cs, italic.cs, size.cs, direction	Complex-Script
contextualSpacing, lineRule, pageBreakBefore, wordWrap	Spacing & Pagination Extras
firstLineChars, hangingChars	Chars-Based Indent
font, font.latin/ea/cs, theme fonts	Fonts
style, rStyle	Styles
shading.val, shading.fill, shading.color	Shading Variants
tabs	Tab Stops
framePr.* (w/h/wrap/hAnchor/vAnchor/hSpace/vSpace)	Text Frame
border (whole-box pBdr)	Paragraph Borders
textAlignment	Vertical Text Alignment
kinsoku, autoSpaceDE, autoSpaceDN, overflowPunct, topLinePunct	EastAsian Typography
suppressLineNumbers, suppressAutoHyphens, mirrorIndents, adjustRightInd, snapToGrid	Line & Indent Flags
divId, textboxTightWrap	Web / Textbox Hints
listStyle, start, numId, numLevel	List Numbering

Inspect the Generated File

# List every paragraph path
officecli query paragraph-formatting.docx paragraph

# Inspect a paragraph's full property set
officecli get paragraph-formatting.docx "/body/p[5]"

# Check the paragraph-mark formatting of a specific paragraph
officecli get paragraph-formatting.docx "/body/p[20]"

# Find all paragraphs with a shading fill set
officecli query paragraph-formatting.docx paragraph --find shading.fill