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:

pie Language Mix
TypeScript 45
Python     30
Rust       25

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:

journey-map A Cabin Boy's First Voyage

persona Squidlips Sam color: blue
  Greenhorn cabin boy, first time at sea
  Sworn to the crew but quietly terrified

[Signing On]
  Sign the articles score: 4, emotion: Hopeful
    description: Captain reads the code aloud — pay shares, no women aboard, lights out at 8

[The Tempest]
  Caught in a squall off the reef score: 1, emotion: Terrified
    pain: Two crewmates lost overboard before dawn
    thought: Maybe the merchant fleet wasn't so bad after all
  Dawn, and she still floats score: 3, emotion: Relieved

[The Prize]
  Strike the colors score: 5, emotion: Triumphant
    description: Heavy with silver from the Veracruz mines

[Homecoming]
  Bury a share on the island score: 5, emotion: Proud
    thought: Three doubloons hidden where only he can find them
  Back to the Rusty Anchor score: 4, emotion: Content
    opportunity: Next time he signs on as a full hand, not a boy

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

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