docs: port the Excalidraw diagram pipeline (machinery only)

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.
This commit is contained in:
Chris Sells 2026-07-10 23:27:38 -07:00
commit 4e97ae25f7
4 changed files with 30 additions and 4 deletions

View file

@ -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/<name>.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.

View file

@ -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/<name>.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

View file