Build Mermaid Chart

0%0 of 20 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

An editor with the diagram source on one side and a rendered view on the other, rendering as you type without losing your place, exporting deterministically so a diagram in a repository produces the same image on any machine, and writing visual adjustments back into the text so there is only ever one source.

estimated effort weekendthe files for this build are in the project pack

RenderingThe diagram language's own renderer, in the browserRuntimeTypeScript with ViteEditorA code editing component with syntax highlighting for the diagram languageExportDeterministic SVG and PNG rendered from the same sourceStorageFiles on disk, or the browser with file open and save

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installfree
Why Runs the build and the batch render command.
Get it nodejs.org, or nvm install 22. open ↗
Verify node --version prints v22 or higher
installfree
Why It is the specification of the language. Reimplementing its layout is a separate project and would diverge immediately.
Get it Install the renderer as a dependency. Pin the version, since a renderer update changes layout and therefore every committed image.
Verify A sample diagram renders to SVG
have readyfree with an open licence
Why Embedding is what makes exports identical across machines, and embedding is redistribution which not every licence permits.
Get it An openly licensed family with its licence file kept alongside.
Verify The licence permits embedding and the exported SVG carries the font
have readyfree
Why Phase 4's determinism check is meaningless on the machine that produced the reference, since it has exactly the fonts that were used.
Get it A container image with a minimal font set is the easiest way, and it is also what your continuous integration will look like.
Verify The same source exports identically in both environments
have readyfree
Why Error handling and re-render performance both need real sources, which are longer and messier than examples and contain the syntax you actually get wrong.
Get it Take the diagrams from a project you maintain, or write the ones you have been meaning to.
Verify At least five real diagrams render, including one large one

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- The source text is the model. These are the derived structures the editor keeps.
- documents(id, path, source, updated_at)
- parse_result(document_id, ok, ast_json, error_line, error_message, parsed_at)
- render_result(document_id, svg, width, height, node_positions_json, rendered_at)
- history(document_id, at, source) · text revisions, since the text is what is worth versioning
- Node positions come out of the renderer and are never stored as input. If a visual edit needs to change one, it must change the text that produced it.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`VITE_RENDERER_VERSION`	required	`pinned-in-package-json`	Pinned, because a renderer update changes layout and therefore every committed image.
`VITE_FONT_PATH`	required	`/fonts/inter.woff2`	Bundled font embedded in exports, with its licence file beside it.
`VITE_RENDER_DEBOUNCE_MS`	required	`250`	Delay before re-rendering while typing. Longer on large diagrams.
`EXPORT_SCALE`	required	`2`	Raster scale for PNG export, rendered from vector at that scale rather than upscaled.
`DIAGRAMS_DIR`	required	`./docs/diagrams`	Where the batch command looks for sources and writes images.

The build, in order

1
Type and see, without losing your place
The diagram updates as you type and the view does not jump around.
1. Code editor with syntax highlighting on one side, rendered output on the other.
  Files src/editor.ts
  terminal
  npm create vite@latest . -- --template vanilla-ts
2. Pan and zoom survive a re-render. Without this, typing is unusable on anything large.
  Files src/preview.ts
3. On a parse failure, show the error beside the previous diagram rather than blanking it.
  Files src/render.ts
done when · tick each as it passes
watch out
- Clearing the preview whenever the source fails to parse means the diagram vanishes on every keystroke that lands mid-token, which is most of them. Keep the last successful render visible, show the error alongside it, and replace only when a new render succeeds.
next phase
2
Errors a person can act on
A mistake in the source tells you where it is and what it expected.
1. Different diagram types report differently. Normalise into one shape.
  Files src/errors.ts
2. The line and, where known, the column. Reading a line number and scrolling is friction.
  Files src/editor.ts
3. Five is enough to start. Add one whenever you confuse yourself.
  Files src/error-map.ts
done when · tick each as it passes
watch out
- Showing the renderer's raw error message is the difference between a tool people learn and one they abandon, because those messages are written for the parser rather than the author. Map the common ones to plain wording, and always show the line.
next phase
3
The visual editing decision
Either a visual change writes back into the text, or there is no visual change.
1. Read-only preview is a legitimate and much simpler answer. Write down which you chose and why.
  Files docs/editing-model.md
2. If you offer them. The gesture produces a source change and nothing else.
  Files src/visual-edit.ts
3. Inspect the saved file. Any extra state is the second source of truth this phase prevents.
done when · tick each as it passes
watch out
- Storing a dragged position in a sidecar file that the diagram language does not know about creates a second source of truth, and the moment someone edits the text in another editor the two disagree with no way to reconcile. Round trip through the text or do not offer the gesture at all.
next phase
4
Export that is the same everywhere
The same source produces the same image on any machine.
1. Rather than relying on what is installed. This is the main source of environment drift.
  Files src/export.ts
2. So the file carries everything needed to reproduce its rendering.
  Files src/document.ts
3. Or a container with a different font set. Comparing on the machine that made it proves nothing.
done when · tick each as it passes
watch out
- A diagram whose export depends on the fonts installed locally will render differently in continuous integration than on a laptop, and the difference shows up as a mysteriously changed image in a pull request. Bundle the font, embed it in the SVG, and verify by rendering somewhere with a different font set.
next phase
5
Diagrams in a repository
A diagram lives beside the code it describes and its changes are reviewable.
1. Directory in, images out, deterministic. Suitable for continuous integration.
  Files src/cli.ts
2. Re-render and compare. Failing the build is what keeps documentation honest.
  Files src/check.ts
3. How to reference the rendered output from your documentation.
  Files README.md
done when · tick each as it passes
watch out
- Committing a rendered image without a check means it drifts from its source silently, and readers see a diagram that no longer matches the text that supposedly produced it. A check that re-renders and compares turns that into a failed build rather than a lie in your documentation.
6
Sharing without pretending to collaborateproduct builder
Someone can view a diagram, and you have not implied multiplayer.
1. Compressed. It is text, which makes this genuinely practical for most diagrams.
  Files src/share.ts
2. So a later edit does not change what someone already has.
  Files src/share.ts
3. In the interface. Silence reads as a promise about collaboration you did not make.
  Files README.md
done when · tick each as it passes
watch out
- Because the source is text, it is tempting to sync it live over a socket, and a naive last-write-wins sync on a text document loses characters when two people type. If you want collaborative text editing, that is a conflict-free data type and a substantial project rather than a socket.

what this build does not replace

Import and export of proprietary diagram formats.
Multiplayer editing.
Presentation and organisational controls.
Exact layout control beyond the language.
high-fidelity import and export
presentation and enterprise controls
multiplayer cursors and comments
large template libraries

after v1, if you want it

A diagram gallery generated from the repository, which makes existing diagrams discoverable
Rendering diagrams from code comments, so an architecture diagram lives next to what it describes
A visual diff of rendered output in pull requests, alongside the text diff

Need the files? The project pack on the verdict page hands your agent the whole brief · more diagrams.