Embedded Diagrams That Stay Current
Every diagram in a document has the same problem. You paste it in, it is correct, and then it quietly stops being correct — because the thing it describes moved and the copy in your docs did not.
Diagrammo embeds work in two layers, and the second one is about that.
The fence
Anywhere a Markdown pipeline runs — Astro, Docusaurus, Fumadocs, Nextra,
VitePress, Obsidian — a fenced block with the language dgmo becomes a
rendered SVG at build time:
That block is the thing it describes — open its source panel and you are looking at the five lines that produced it.
No client JavaScript, no iframe, no image host. The SVG is in your HTML, it prints, it works with your color-mode toggle, and it is diffable in your repository because the source sits right there in the file.
That is the whole of layer one, and for most diagrams it is enough. The source lives next to the prose it explains, so it gets updated by whoever is updating the prose.
The live link
It stops being enough the moment two documents describe the same thing. Now you have two copies of a diagram, and no way to know when one of them drifts.
So a fence can name a diagram instead of carrying it:
gantt Product roadmap — Q4 2026
start-date 2026-10-01
tag Team as t
Web blue
Cloud green
Docs orange
marker 2026-11-17 Public beta red
era 2026-12-21 -> 2027-01-04 Holiday freeze gray
[Foundations] t: Cloud
Usage metering 2w t: Cloud, progress: 100
-> Billing portal 3w t: Web, progress: 60
Team spaces 4w t: Cloud, progress: 40
[Beta] t: Web
Onboarding tour 2w t: Web, progress: 20
Embed docs 1w t: Docs, progress: 100
Beta invites 1w t: Web
-> Feedback triage 3w t: Web
[Launch] t: Docs
Pricing page 1w t: Docs
Launch post 3d t: Docs
-> General availability 0dThat diagram lives in Diagrammo Cloud. The block above is not a picture of it — it was fetched and rendered when this page was built, and the page will pick up whatever the diagram says the next time it builds. Edit it once; every document pointing at it follows.
The link comes from the app. Open the diagram in Diagrammo and press Share on the left rail (or ⌘E), then Show on the web → Show — or right-click it in the file list and choose Show and copy link. The link lands on your clipboard, and the diagram’s row wears an amber globe from then on (see where these are in the app). Paste the whole link into the fence:
```dgmo
https://online.diagrammo.app/d/dgm_01M3PG3EEZZ4M1Y54R7AEB3E25
```The short live-link <id> form above does the same job once you know the id.
Three practical things fall out of that, and they are the parts worth knowing before you use it.
The source is committed, not just cached. Resolving a live link writes what
it fetched into .dgmo/references/ in your repository, and you commit that
directory. It means a clean CI checkout builds from a file you can read rather
than from our uptime — if we are unreachable, your site builds anyway, from the
last copy, and warns. It also means a diagram changing shows up in your pull
request as a source diff, which is a thing a reviewer can actually look at.
A live link that never resolved fails your build. That one is deliberate. An id that has never worked can only be a typo, and it is cheapest to hear about one line from where you made it. Every other failure is softer: an unreachable server renders the committed copy, and a diagram whose author stopped showing it renders a plain “no longer shared” card rather than continuing to publish something somebody took back.
Only published diagrams can be linked. There is no token to configure and no allowlist to maintain, because a private diagram simply is not fetchable. That constraint is what keeps the whole path cacheable, and it is why a live link costs a page almost nothing.
Which layer you want
Paste the source when the diagram belongs to the document. Reference it when the diagram belongs to the system and the document is only one of the places that talks about it.
Embeds are documented per framework at diagrammo.app/embed.