Skip to content

README.md

Latest commit

 

History

History
82 lines (61 loc) · 3.55 KB

README.md

File metadata and controls

82 lines (61 loc) · 3.55 KB
Raw

Excalidraw Diagram Workbench

An opinionated starter repo for generating, editing, and exporting Excalidraw diagrams for many different projects.

繁體中文README.zh-TW.md

What this repo includes

  • A vendored Excalidraw renderer under .claude/skills/excalidraw-diagram/references/ (also projected for agents under .agents/skills/excalidraw-diagram)
  • A generic sample renderer in generate_diagram.js
  • A reusable render script in render_excalidraw.sh
  • A pre-render structural validator in validate_excalidraw.sh (text overflow + arrow-binding consistency)
  • Generated diagram files in output/

Quick start

Recommended editor: VS Code with the pomdtr.excalidraw-editor extension for directly editing .excalidraw files inside the workspace.

  1. Generate or update a diagram JSON file:
node generate_diagram.js /absolute/path/to/my-diagram.json

When a spec path is given, the output .excalidraw file is written next to the spec automatically. Without a spec path, examples/channel-map.example.json is used as the default spec and the diagram JSON is written to stdout. Use --dark for the dark theme.

  1. Validate structure before rendering (catches text-overflowing-its-box and broken arrow bindings):
./validate_excalidraw.sh                                  # batch over output/ + temp/
./validate_excalidraw.sh /absolute/path/to/file.excalidraw
./validate_excalidraw.sh /absolute/path/to/file.excalidraw --fix   # auto-fix safe binding issues
  1. Render the .excalidraw file to PNG:
./render_excalidraw.sh
  1. Render a different .excalidraw file when needed:
./render_excalidraw.sh /absolute/path/to/your-diagram.excalidraw

Default workflow

  • Keep rendering logic in generate_diagram.js, and keep diagram content in JSON spec files.
  • Edit .excalidraw files directly in Excalidraw, or replace the sample renderer with your own generator.
  • Run ./validate_excalidraw.sh first — text overflow and binding issues are cheap to catch before any PNG is rendered.
  • Run ./render_excalidraw.sh <file> to render to PNG.
  • Add more generators or templates as your diagram library grows.

Repository structure

.
├── .claude/
│   └── skills/
│       └── excalidraw-diagram/
│           └── references/
├── .agents/
│   └── skills/
│       └── excalidraw-diagram/
├── examples/
│   └── channel-map.example.json
├── generate_diagram.js
├── lib/
├── output/
├── render_excalidraw.sh
└── validate_excalidraw.sh

Notes

  • This repo recommends VS Code and includes .vscode/extensions.json with pomdtr.excalidraw-editor.
  • The render script prefers the vendored renderer under .claude/skills/excalidraw-diagram/references/, so the project is portable across machines.
  • The vendored renderer loads Excalidraw from a pinned jsdelivr ESM build first, then falls back to the unpkg UMD build. If both fail, it prints browser request/page errors instead of hanging on a generic Playwright timeout.
  • The validator measures text width with the same canvas + Excalidraw font stacks the renderer uses, so detected overflows match what would actually appear in the PNG (no character-count estimation).
  • .claude/ is the source of truth. .agents/skills/excalidraw-diagram is generated from it by node ~/.claude/scripts/sync-to-agents.mjs.
  • generate_diagram.js is a reusable sample renderer. The repo stays generic by moving concrete diagram content into spec files instead of hardcoding it in the JS source.