61e0688f73
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>
72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# 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](https://app.diagrams.net/) 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
|
|
|
|
1. **Clone** the repo (you likely already have it if you're editing):
|
|
```bash
|
|
git clone https://gitea.wbd-rd.nl/RnD/pumpingStation.git
|
|
cd pumpingStation/wiki/diagrams
|
|
```
|
|
2. **Open** the `.drawio` file in draw.io:
|
|
- Web: [app.diagrams.net](https://app.diagrams.net/) → *Open Existing Diagram*, or drag-and-drop.
|
|
- Desktop: [drawio-desktop](https://github.com/jgraph/drawio-desktop/releases).
|
|
3. **Edit** — move shapes, change labels, adjust layout.
|
|
4. **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).
|
|
5. **Commit & push** both files:
|
|
```bash
|
|
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/`:
|
|
|
|
```markdown
|
|
|
|
```
|
|
|
|
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
|
|
|
|
1. Open draw.io, start blank.
|
|
2. Draw it.
|
|
3. `File → Save As…` → `wiki/diagrams/<name>.drawio`.
|
|
4. `File → Export as → SVG…` with **Include a copy of my diagram** checked → save as `wiki/diagrams/<name>.drawio.svg`.
|
|
5. Reference from the wiki page with ``.
|
|
6. Add an entry to the table above.
|
|
7. 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.)
|