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:
parent
cc9601f85c
commit
4e97ae25f7
4 changed files with 30 additions and 4 deletions
|
|
@ -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.
|
||||
|
|
|
|||
24
Makefile
24
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/<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
|
||||
|
|
|
|||
0
docs/diagrams/excalidraw-rendered/.gitkeep
Normal file
0
docs/diagrams/excalidraw-rendered/.gitkeep
Normal file
0
docs/diagrams/excalidraw/.gitkeep
Normal file
0
docs/diagrams/excalidraw/.gitkeep
Normal file
Loading…
Add table
Add a link
Reference in a new issue