dsh-skills/skills/drawio-skill/references/mermaid-authoring.md

Mermaid authoring → native .drawio

Read this when the diagram is a standard type with no custom styling needs and the draw.io CLI is version ≥ 30 — writing Mermaid text and letting the CLI convert it is faster and safer than hand-placing XML: you only get the structure right, layout comes free.

# .mmd in → laid-out, editable, native .drawio out (draw.io desktop ≥ 30)
drawio -x -f xml -o diagram.drawio diagram.mmd
# then continue the normal workflow (validate → preview PNG → self-check → …)

Version gate (critical): on draw.io ≤ 29 the .mmd input fails with Export failed, and the --layout flag corrupts argument parsing entirely (like the -w pitfall). Resolve the CLI version in workflow step 1 (drawio --version); if it prints < 30, skip both this path and --layout, and author XML instead (optionally suggest brew upgrade --cask drawio).

Never export a .mmd straight to an image: direct Mermaid → PNG with -e crashes current draw.io desktop builds (electron UnhandledPromiseRejection, then hang — verified on 30.2.6). Always convert to .drawio first (-f xml), then run the normal export on the .drawio — the two-step path embeds the diagram XML reliably.

When to prefer which authoring mode

Author as	Best for	Why
Mermaid → CLI convert	flowchart, state, gantt, timeline, journey, pie, quadrant, sankey, gitGraph, mindmap, kanban, requirement, block, xychart, radar, wardley, C4 sketches	structure-only input, free layout, 28 types
XML (this skill's core path)	anything needing official vendor icons (shapesearch/aiicons), style presets, swimlanes, precise positions, edge waypoint control, multi-page/drill-down	Mermaid can't express draw.io styles/shapes
Bundled generators	code/IaC/SQL imports, sequence (seqlayout), C4 with drill-down (c4.py)	deterministic, data-driven

Routing note: this converts Mermaid into a .drawio deliverable. If the user wants Mermaid text that lives in git / renders in Markdown, route to the mermaid skill instead (see "When to use / when NOT to use").

Mermaid quirks that matter for draw.io's parser

Condensed from the upstream reference (jgraph/drawio-mcp shared/mermaid-reference.md, Apache-2.0):

• The first non-directive line's keyword selects the type — a misspelled header yields a blank diagram. Common: flowchart TD, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, mindmap, timeline, journey, pie, gitGraph, quadrantChart, sankey-beta, kanban, c4Context.
• Node IDs are identifiers (A, node_1) — no spaces, no trailing punctuation, avoid reserved words (end, class, subgraph). Display text goes in brackets/quotes: A["User's Account"].
• One statement per line; quote labels containing :, -, parentheses, or non-ASCII (use ", not ').
• Only <br>, <b>, <i>, <u> are reliable HTML in labels; hex colors only (#fff, never rgb()).
• Styling: style A fill:#f9f,stroke:#333, reusable classDef x fill:#dfd + A:::x, edge linkStyle 0 stroke:#f00.
• Never apply --layout to a Mermaid-converted file — it is already laid out.
• Match label language to the user's language.

After converting, treat the .drawio as the artifact (delete the .mmd) and continue at the validate → export draft steps as usual. The converted file uses UserObject-wrapped cells — validate.py handles those.

ELK --layout pass (XML-authored diagrams, CLI ≥ 30)

For XML you authored with rough (or all-zero) positions, the CLI can run the editor's ELK layouts — an alternative to autolayout.py when Graphviz is unavailable, and the better choice for organic/radial shapes (networks, mind-map-like graphs) that dot lays out poorly:

# in-place re-layout (reading and overwriting the same path is supported)
drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio
# or layout + export in one call
drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio

Preset	Layout
verticalFlow / horizontalFlow	layered — flowcharts, pipelines
verticalTree / horizontalTree / radialTree	trees — hierarchies, org charts
organic	force-directed — networks, mind maps

Finer control: pass a JSON array instead of a preset — --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT","elk.spacing.nodeNode":40}}]' (algorithms: elkLayered, elkTree, elkRadial, elkOrganic, elkStress, elkBox).

Choosing between layout engines: autolayout.py (Graphviz) understands this skill's graph-JSON pipeline (importers, groups→clusters, --tune, palette tinting) — prefer it when that pipeline is in play. Use --layout when Graphviz is missing, when re-laying-out an existing .drawio, or for organic/radial topologies.