Files

znetsixe 61e0688f73 Make starter SVG diagrams round-trippable in draw.io

Each <name>.drawio.svg now has the corresponding <name>.drawio XML
embedded as content="..." on the root <svg> element. Opening the
SVG in draw.io (File → Open, or drag-drop) loads the full editable
model — no need to keep the .drawio file around for editing.

Updated diagrams/README.md to reflect that both file formats are
now round-trippable from the start.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 13:00:16 +02:00

3.2 KiB

Raw Blame History

Diagrams

Editable source diagrams for the pumpingStation wiki. Each diagram is a .drawio + .drawio.svg pair, so anyone can edit the source in draw.io without touching any Markdown.

Why two files?

File	Role
`<name>.drawio`	Native draw.io XML. The canonical source.
`<name>.drawio.svg`	SVG export of the same diagram (with source embedded). What the wiki actually renders, and what round-trips back into draw.io.

Checking both in means the wiki renders for everyone, and the next editor picks up from exactly where the last one left off.

Editing workflow

Clone the repo (you likely already have it if you're editing):

git clone https://gitea.wbd-rd.nl/RnD/pumpingStation.git
cd pumpingStation/wiki/diagrams

Open the .drawio file in draw.io:
- Web: app.diagrams.net → Open Existing Diagram, or drag-and-drop.
- Desktop: drawio-desktop.
Edit — move shapes, change labels, adjust layout.
Export to SVG with the source embedded:
- File → Export as → SVG…
- Check Include a copy of my diagram ← this is what lets future edits round-trip through the SVG.
- Save next to the source as <name>.drawio.svg (overwrite).

Commit & push both files:

git add wiki/diagrams/<name>.drawio wiki/diagrams/<name>.drawio.svg
git commit -m "Update <name>: <what changed>"
git push

Referencing a diagram from a wiki page

In any Markdown page under wiki/:

![Basin model](diagrams/basin-model.drawio.svg)

Use a descriptive alt text; it's the fallback if the SVG fails and it shows up in exports.

Naming

kebab-case, one concept per diagram.
Current diagrams:

Diagram	Shows
`basin-model`	Physical basin cross-section — walls, pipes at their real heights, control thresholds cutting across, zone labels
`control-zones`	Vertical level axis ("thermometer") for `levelbased` mode — STOP / DEAD ZONE / RUN with demand ramp
`safety-rules`	Dry-run vs overfill rule asymmetry — which children stop, which keep running

Making a brand-new diagram

Open draw.io, start blank.
Draw it.
File → Save As… → wiki/diagrams/<name>.drawio.
File → Export as → SVG… with Include a copy of my diagram checked → save as wiki/diagrams/<name>.drawio.svg.
Reference from the wiki page with ![alt](diagrams/<name>.drawio.svg).
Add an entry to the table above.
Commit all three files together (.drawio, .drawio.svg, updated .md).

These starters are rough

The .drawio files and their matching .drawio.svg exports committed here are placeholders — layout is approximate, colors and fonts are defaults, no fine alignment. They're meant to be a starting point; open them in draw.io and refine.

Both formats are round-trippable: open either the .drawio or the .drawio.svg in draw.io and it will load the editable model. (The SVG has the drawio XML embedded in a content="…" attribute on the root <svg> element — that's what lets draw.io re-open its own SVG exports.)

3.2 KiB Raw Blame History