|
| 1 | +--- |
| 2 | +name: drawio-diagrams |
| 3 | +description: Create and edit draw.io / diagrams.net diagrams as editable .drawio.svg files for embedding in Marp slides or docs. Use when the user asks to "make a draw.io diagram", "create a .drawio.svg", "add an architecture/flowchart diagram I can edit in draw.io", or wants an SVG that both renders as an image and reopens editable in draw.io. Covers the editable .drawio.svg format, authoring the mxGraphModel XML, a dependency-free helper that renders a node/edge spec, extracting/editing embedded XML, and embedding the result in slides. Prefer Mermaid for quick throwaway diagrams; use this when the diagram must stay editable in draw.io. |
| 4 | +--- |
| 5 | + |
| 6 | +# draw.io Diagrams (.drawio.svg) |
| 7 | + |
| 8 | +## What `.drawio.svg` is |
| 9 | + |
| 10 | +A `.drawio.svg` is a normal SVG **plus** an editable draw.io model. The root |
| 11 | +`<svg>` element carries a `content="…"` attribute holding the draw.io `mxfile` |
| 12 | +XML, HTML-escaped. Because of this dual nature the same file: |
| 13 | + |
| 14 | +- **renders as an image** in Markdown, Marp, browsers, and GitHub, and |
| 15 | +- **reopens fully editable** in [draw.io / diagrams.net](https://app.diagrams.net), |
| 16 | + the desktop app, or the *Draw.io Integration* VS Code extension |
| 17 | + (`hediet.vscode-drawio`). |
| 18 | + |
| 19 | +Store diagrams under `slides/img/` (per project convention) and embed them like |
| 20 | +any other image: |
| 21 | + |
| 22 | +```markdown |
| 23 | + |
| 24 | + |
| 25 | +``` |
| 26 | + |
| 27 | +> Marp exports SVGs fine; for **PDF/PPTX** export of *local* files pass |
| 28 | +> `--allow-local-files` to Marp CLI (the Pages workflow already does for PDF). |
| 29 | +
|
| 30 | +## Two ways to author |
| 31 | + |
| 32 | +### A. Helper script (recommended for boxes-and-arrows) |
| 33 | + |
| 34 | +`make-drawio-svg.mjs` (in this folder) renders a small JSON node/edge **spec** |
| 35 | +to SVG shapes *and* embeds a matching `mxGraphModel`, so the output is editable |
| 36 | +in draw.io with **no draw.io install and no npm packages** (plain Node). |
| 37 | + |
| 38 | +```bash |
| 39 | +# Build an editable diagram from a spec |
| 40 | +node .github/skills/drawio-diagrams/make-drawio-svg.mjs build spec.json -o slides/img/flow.drawio.svg |
| 41 | + |
| 42 | +# Print the embedded draw.io XML of an existing file (to inspect or edit) |
| 43 | +node .github/skills/drawio-diagrams/make-drawio-svg.mjs extract slides/img/flow.drawio.svg |
| 44 | +``` |
| 45 | + |
| 46 | +Spec format (`example.spec.json` is a complete sample; `example.drawio.svg` is |
| 47 | +its rendered output): |
| 48 | + |
| 49 | +```json |
| 50 | +{ |
| 51 | + "nodes": [ |
| 52 | + { "id": "a", "label": "Start", "x": 200, "y": 40, |
| 53 | + "width": 140, "height": 50, |
| 54 | + "fill": "#d5e8d4", "stroke": "#82b366", "rounded": true }, |
| 55 | + { "id": "b", "label": "Do work", "x": 200, "y": 140, |
| 56 | + "width": 140, "height": 60, "fill": "#dae8fc", "stroke": "#6c8ebf" } |
| 57 | + ], |
| 58 | + "edges": [ |
| 59 | + { "source": "a", "target": "b", "label": "next" } |
| 60 | + ] |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +Node fields: `id` (required, unique), `label` (use `\n` for line breaks), |
| 65 | +`x`/`y`/`width`/`height` (required, pixels), `fill`, `stroke`, `fontColor`, |
| 66 | +`rounded` (bool), and optional `style` for raw draw.io style fragments |
| 67 | +(e.g. `"shape=cylinder"`). Edge fields: `source`, `target` (node ids), optional |
| 68 | +`label`, optional `orthogonal: true` for elbow routing. |
| 69 | + |
| 70 | +Layout tips: lay nodes top-to-bottom or left-to-right on a ~20px grid; give |
| 71 | +~40–60px gaps so straight edges do not cross boxes. draw.io re-routes edges with |
| 72 | +its own algorithm on open, so exact edge paths may shift slightly — the node |
| 73 | +geometry is authoritative and preserved. |
| 74 | + |
| 75 | +### B. Hand-authored mxGraphModel |
| 76 | + |
| 77 | +For richer diagrams, write the `mxGraphModel` XML yourself and use draw.io's |
| 78 | +renderer. The model uses `<mxCell>` elements under `<root>`: |
| 79 | + |
| 80 | +- `<mxCell id="0"/>` and `<mxCell id="1" parent="0"/>` are the required root layers. |
| 81 | +- A **vertex**: `<mxCell id="n1" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell>` |
| 82 | +- An **edge**: `<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" parent="1" source="n1" target="n2"><mxGeometry relative="1" as="geometry"/></mxCell>` |
| 83 | + |
| 84 | +Wrap it as `<mxfile><diagram name="Page-1"><mxGraphModel>…</mxGraphModel></diagram></mxfile>`. |
| 85 | +To turn hand-written XML into a rendered, editable file without a local draw.io |
| 86 | +install, use the draw.io desktop CLI or its headless Docker image, e.g.: |
| 87 | + |
| 88 | +```bash |
| 89 | +# draw.io desktop CLI (renders AND embeds the source for editability) |
| 90 | +drawio --export --format svg --embed-diagram diagram.drawio -o slides/img/diagram.drawio.svg |
| 91 | +``` |
| 92 | + |
| 93 | +## Editing an existing diagram |
| 94 | + |
| 95 | +1. `extract` the embedded XML: `make-drawio-svg.mjs extract file.drawio.svg > model.xml`. |
| 96 | +2. Edit `model.xml` (change labels, add cells, adjust geometry), **or** just edit |
| 97 | + the original spec JSON if the file was built from one. |
| 98 | +3. Regenerate: rebuild from the spec, or (for hand-authored XML) re-export with |
| 99 | + the draw.io CLI so the rendered shapes and embedded `content` stay in sync. |
| 100 | +4. Easiest of all: open the `.drawio.svg` directly in the *Draw.io Integration* |
| 101 | + VS Code extension and edit visually — it saves the SVG + embedded model for you. |
| 102 | + |
| 103 | +## When to use this vs Mermaid |
| 104 | + |
| 105 | +- **Mermaid** (already supported in this template): fast, text-only, great for |
| 106 | + quick flowcharts/sequence diagrams rendered live in the deck. Not editable in |
| 107 | + draw.io. |
| 108 | +- **draw.io `.drawio.svg`**: pixel-level control, custom shapes/colors, and it |
| 109 | + stays editable in a visual editor. Prefer it for architecture diagrams or any |
| 110 | + figure that will be revised in draw.io later. |
| 111 | + |
| 112 | +## Verifying output |
| 113 | + |
| 114 | +- The file must be well-formed XML and its root `<svg>` must have a `content` |
| 115 | + attribute — otherwise it renders but is **not** editable in draw.io. |
| 116 | +- Quick check: `make-drawio-svg.mjs extract file.drawio.svg` should print a |
| 117 | + `<mxfile>…</mxfile>` document without error. |
0 commit comments