1# excalidraw
2
3sublimated renders `.excalidraw` files as diagrams. push via [git](../git/), view the rendered diagram on the web.
4
5- diagrams are rendered server-side on push — no client-side JavaScript needed
6- the rendered SVG is stored alongside the source, so viewing is instant
7- edit mode shows the raw JSON (visual editor planned)
8- fonts are embedded — all 21 excalidraw font families render correctly without external requests
9- inline comments and reactions work on the rendered diagram (SVG is inline DOM)
10
11## demos
12
13- [simple](simple.excalidraw) — rectangles, arrows, text
14- [flowchart](flowchart.excalidraw) — a basic flowchart with decisions
15- [architecture](architecture.excalidraw) — system architecture diagram
16- [wireframe](wireframe.excalidraw) — simple UI wireframe
17- [freehand](freehand.excalidraw) — freedraw and ellipses
18
19## how it works
20
211. push a `.excalidraw` file via git (or save via edit mode)
222. sublimated detects the file type and sends it to the excalidraw renderer (pure SVG, no canvas/DOM)
233. the rendered SVG is stored in CAS as a `render_svg` representation
244. when you view the file, the SVG is displayed inline
255. if rendering fails (invalid JSON), the source is shown as highlighted code
26
27## file format
28
29excalidraw files are JSON with this structure:
30
31```json
32{
33  "type": "excalidraw",
34  "version": 2,
35  "elements": [...],
36  "appState": { "viewBackgroundColor": "#ffffff" }
37}
38```
39
40each element has a type (rectangle, ellipse, diamond, arrow, line, freedraw, text, image, frame), position, size, style properties (strokeColor, backgroundColor, fillStyle, roughness, etc).
41
42## visual diffing (planned)
43
44the renderer supports element-level diffing — comparing two versions of an excalidraw file to show added, removed, and modified elements with color coding. this will be used in the version comparison view.