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