Skip to content

@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.

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:

  1. 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 mode C4InteractiveRenderer lets 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). applyC4Edit in ./core turns 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.
  2. No persistence. @liminis/diagrams never writes anywhere. C4InteractiveRenderer reports 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.
  3. Element IDs are fence-local. C4Element.id is unique within one parsed diagram only. It carries no identity across two diagrams — two System(app, ...) blocks in different files have nothing connecting their app IDs. 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.
  4. No cross-diagram link syntax. There is no Rel that 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 !include is 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.
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?