@liminis/diagrams documentation
This is documentation for someone building a tool on top of @liminis/diagrams —
a CLI, a CI job, a wiki, a different editor. It answers the questions the top-level
README.md quick start doesn’t: what the layout result contains, how
manual positions interact with dagre, what the parser accepts and silently discards,
and which parts of a “C4 editing experience” live here versus in
@liminis/editor.
There is a live demo if you would rather see it than read about it — it runs the published package, so what you drag there is what you install.
Limitations — read this first
Section titled “Limitations — read this first”The most expensive mistake a tool builder can make against this package is invisible until you’ve already built against it. Four things this package does not do:
- Structural editing is reported, not applied — and it is narrow. No textarea
overlay, no click-to-edit of existing text, no layout-mode toolbar, no dark-mode
auto-detection: those are Lexical-bound and stayed behind in
@liminis/editor(C4Component.tsx), so a host still needs its own “edit the source text” surface. What the package does offer (from 0.2.0) is adding: in edit modeC4InteractiveRendererlets a user add an element or an empty boundary (right-click the canvas, or long-press on touch, pick a kind, name it inline) and add a relationship (drag from one element to another, then label it inline), and reports each as an edit. It also lets a user rename an element or a relationship (double-click it, or tap it and use Rename on touch) and move an element or boundary into or out of another boundary (drop it on the boundary, ⌥-drag to move out, or Move out on touch).applyC4Editin./coreturns that edit into new source text — one inserted block (one line, or two for an added boundary) for an add, just the label argument replaced for a rename, or one block moved and re-indented for a re-parent, nothing else touched — and the host applies it. Delete, changing an element’s kind and editing a description or technology are not supported; those stay source edits. See Recipe 4. - No persistence.
@liminis/diagramsnever writes anywhere.C4InteractiveRendererreports position changes and edits via callbacks; storing them — in a file, a database, a fenced code block’s meta string, wherever — is entirely the host’s job. See Recipe 3. - Element IDs are fence-local.
C4Element.idis unique within one parsed diagram only. It carries no identity across two diagrams — twoSystem(app, ...)blocks in different files have nothing connecting theirappIDs. Anything that wants stable cross-file identity (file#id, a declared namespace, a URN) has to establish it in a layer above this package, over several already-parsed diagrams. - No cross-diagram link syntax. There is no
Relthat spans two diagrams, and no “this container is detailed in another diagram” relationship — which is exactly the C4 zoom-level relationship a linked set of diagrams wants. You can’t improvise one either: an unrecognized macro name is a parse error, not a silently-ignored no-op, and!includeis recognized but stripped, so the included file is never fetched or inlined. Adding it means extending the parser, or carrying the link beside the diagram in fence meta or frontmatter.
Contents
Section titled “Contents”| Page | Answers |
|---|---|
| Architecture | Which entry point (., ./core, ./react, ./server) should I install, and why? |
| C4-PlantUML reference | Will my existing C4-PlantUML source parse? What gets silently stripped? |
| Data model | What does a parsed diagram / layout result actually contain? (the centerpiece) |
| Recipes | Complete, runnable examples: headless SVG rendering, embedding the interactive renderer, persisting positions. |
| GitHub | How do I get GitHub to show a rendered C4 diagram in a markdown file? |
| Claude Code | How do I get Claude to render a real C4 diagram instead of hand-drawing one? |