iofficeai--officecli/examples/word/diagram.md

Mermaid Diagrams in Word

The same --type diagram element as PowerPoint, targeting a .docx body. Render Mermaid source two ways:

• render=native — the built-in synthesizer draws editable Word drawing shapes + connectors (no browser). Supported types: flowchart / graph and sequenceDiagram. These are floating shapes anchored to the page margin, so give each native diagram its own page (a page break) to avoid overlapping text.
• render=image — real mermaid.js (headless Chrome / Chromium / Edge) renders a full-fidelity PNG covering every mermaid type. The picture is inline, so it flows with the text like any image — the natural choice inside a flowing document. The mermaid source is stamped into the picture's alt-text.
• render=auto (default) — image when a browser is present, else native.

This demo ships four files:

• diagram.sh — CLI build script (officecli add report.docx /body --type diagram).
• diagram.py — SDK twin, regenerates the same document.
• diagram.docx — the generated document.
• diagram.md — this file.

A diagram is an ADD-ONLY synthesizer (like equation): there is no persistent diagram node. The whole picture is wrapped in one object and add returns its path — a group in native mode (/body/group[N]), an inline picture in a paragraph in image mode. Word has no slide, so there is no x/y and no poster (those are pptx-only); width/height fit the diagram (aspect preserved).

Regenerate

cd examples/word
bash diagram.sh          # or: python3 diagram.py
# → diagram.docx

render=image diagrams need a headless browser. Without one, use render=auto (the default) and they fall back to native shapes.

Document

Page(s)	Mode	Type	Source prop
native	native	flowchart	mermaid=
native	native	sequenceDiagram	text=
image	image	flowchart (same source)	dsl=
image	image	pie	src= (.mmd file)
image	image	classDiagram, stateDiagram-v2, erDiagram, gantt, journey, gitGraph, mindmap, timeline, quadrantChart, requirementDiagram, C4Context, sankey-beta, xychart-beta, block-beta, packet-beta, kanban, architecture-beta, radar-beta	text=

Native — editable shapes (each on its own page)

# flowchart — full node-shape vocabulary; page break isolates the floating group
officecli add diagram.docx /body --type paragraph \
  --prop text="render=native — flowchart" --prop bold=true --prop size=16 --prop pageBreakBefore=true
officecli add diagram.docx /body --type diagram \
  --prop render=native \
  --prop mermaid="flowchart TD
  A([Start]) --> B{Decision}
  B -->|yes| C[Process]
  B -->|no| D[(Database)]
  C --> E[[Subroutine]]" \
  --prop width=12cm

# sequenceDiagram (text= is an alias of mermaid=)
officecli add diagram.docx /body --type diagram \
  --prop render=native \
  --prop text="sequenceDiagram
  participant U as User
  participant S as Server
  U->>S: Login request
  S-->>U: Session token" \
  --prop width=13cm

Node shapes: ([stadium]), {diamond}, [rect], [(database)], [[subroutine]], {{hexagon}}, [/parallelogram/], ((circle)). Edges: -->|label|, -.-> (dashed), ==> (thick), --x (cross end).

Native diagrams are floating shapes. Add a pageBreakBefore=true heading before each so the anchored group does not overlap the surrounding text.

Image — inline PNGs that flow with the text

# Same flowchart as a PNG (dsl= alias). Inline, so it flows after the paragraph.
officecli add diagram.docx /body --type diagram \
  --prop render=image --prop dsl="flowchart TD; A([Start]) --> B{Decision} --> C[Process]" \
  --prop width=14cm

# Load the source from a .mmd file with src= (any mermaid type — pie is not native)
cat > pie.mmd << 'EOF'
pie showData title Traffic Sources
    "Organic Search" : 45
    "Direct" : 30
EOF
officecli add diagram.docx /body --type diagram \
  --prop render=image --prop src=pie.mmd --prop width=10cm

The rest of the gallery passes the source inline with text=: classDiagram, stateDiagram-v2, erDiagram, gantt, journey, gitGraph, mindmap, timeline, quadrantChart, requirementDiagram, C4Context, sankey-beta, xychart-beta, block-beta, packet-beta, kanban, architecture-beta, radar-beta.

Complete Property Coverage

Property	Meaning	Where
mermaid	Canonical source (header line picks the diagram kind)	native flowchart
text	Alias of mermaid	native sequence + gallery
dsl	Alias of mermaid	image flowchart
src (path)	Load source from a .mmd file	pie
render=native	Editable shapes + connectors (no browser)	flowchart, sequence
render=image	Full-fidelity inline PNG via mermaid.js (needs a browser)	the gallery
render=auto	Image when a browser is present, else native (default)	—
width / height	Fit the diagram (aspect preserved)	every diagram

Word has no x / y (no canvas coordinates — diagrams sit in the text flow) and no poster (no slide to grow). Those are pptx-only. See ppt/diagram.md for the pptx version, which adds them.

Manipulate a native diagram after Add (get / set / remove)

add returns the group path for a native diagram:

officecli get diagram.docx '/body/group[1]'                  # read the box back
officecli set diagram.docx '/body/group[1]' --prop width=8cm  # resize (fonts re-bake)
officecli remove diagram.docx '/body/group[1]'               # delete group + children

An image diagram is an inline picture in a paragraph — address it like any picture.

Inspect the Generated File

officecli view diagram.docx outline
officecli get diagram.docx '/body/group[1]'      # native flowchart — editable shapes