From 4e97ae25f7474dcc4e93fa13e2c1391f194d703b Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Fri, 10 Jul 2026 23:27:38 -0700 Subject: [PATCH] docs: port the Excalidraw diagram pipeline (machinery only) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit make diagrams-excalidraw renders committed .excalidraw sources under docs/diagrams/excalidraw/ to SVGs in docs/diagrams/excalidraw-rendered/ (idempotent, @swiftlysingh/excalidraw-cli via npx), matching the Gas City convention. No diagrams authored yet — the nine existing diagrams stay mermaid. The beads-docs skill names the real target and paths. --- .claude/skills/beads-docs/SKILL.md | 10 +++++---- Makefile | 24 ++++++++++++++++++++++ docs/diagrams/excalidraw-rendered/.gitkeep | 0 docs/diagrams/excalidraw/.gitkeep | 0 4 files changed, 30 insertions(+), 4 deletions(-) create mode 100644 docs/diagrams/excalidraw-rendered/.gitkeep create mode 100644 docs/diagrams/excalidraw/.gitkeep diff --git a/.claude/skills/beads-docs/SKILL.md b/.claude/skills/beads-docs/SKILL.md index bcf0d4264..b5c3db822 100644 --- a/.claude/skills/beads-docs/SKILL.md +++ b/.claude/skills/beads-docs/SKILL.md @@ -157,10 +157,12 @@ not drift from the code). ## 7. Diagrams Mermaid fences render natively — prefer them for graphs and flows. For richer -diagrams use the Excalidraw pattern from Gas City: commit the `.excalidraw` -source next to the rendered `.svg`, keep labels short (a two-line "Name / -role" beats a sentence crammed in a box), and embed with descriptive alt -text. Two non-negotiables: +diagrams use the Excalidraw pipeline: author the `.excalidraw` source under +`docs/diagrams/excalidraw/`, render with `make diagrams-excalidraw` (source +and rendered `.svg` are both committed), embed as +`/diagrams/excalidraw-rendered/.svg` with descriptive alt text, and +keep labels short (a two-line "Name / role" beats a sentence crammed in a +box). Two non-negotiables: - **Rasterize and look at every rendered diagram** — text overflow and layout problems are invisible in a text diff. diff --git a/Makefile b/Makefile index fea217365..cce82f5f8 100644 --- a/Makefile +++ b/Makefile @@ -251,6 +251,30 @@ check-docs: @./scripts/check-doc-freshness.sh @go test ./test/docsync +# Render committed Excalidraw diagram sources to SVG (idempotent; only +# re-renders when the .excalidraw source is newer than its .svg). Both the +# source and the rendered SVG are committed; docs pages embed +# /diagrams/excalidraw-rendered/.svg. Rendered images must be looked +# at before committing — layout problems are invisible in a text diff. +diagrams-excalidraw: + @set -e; \ + src_dir=docs/diagrams/excalidraw; \ + out_dir=docs/diagrams/excalidraw-rendered; \ + mkdir -p "$$out_dir"; \ + shopt -s nullglob 2>/dev/null || true; \ + rendered=0; \ + for f in "$$src_dir"/*.excalidraw; do \ + [ -e "$$f" ] || continue; \ + base=$$(basename "$$f" .excalidraw); \ + out="$$out_dir/$$base.svg"; \ + if [ ! -e "$$out" ] || [ "$$f" -nt "$$out" ]; then \ + echo "excalidraw -> $$out"; \ + npx -y @swiftlysingh/excalidraw-cli convert "$$f" --format svg --padding 16 --output "$$out"; \ + rendered=$$((rendered+1)); \ + fi; \ + done; \ + echo "excalidraw: rendered $$rendered file(s)" + # Live preview of the Mintlify docs site (docs/) at http://localhost:3000 docs-dev: ./mint.sh dev diff --git a/docs/diagrams/excalidraw-rendered/.gitkeep b/docs/diagrams/excalidraw-rendered/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/diagrams/excalidraw/.gitkeep b/docs/diagrams/excalidraw/.gitkeep new file mode 100644 index 000000000..e69de29bb