Live Links

A live link is a diagram fence that names a diagram shown on the web from the Diagrammo app instead of carrying its own source. The page shows the publisher’s current version, so a diagram you don’t own, or one maintained somewhere else, never goes quietly out of date in your docs.

The amber globe

A live link always starts in the app, on a diagram somebody shows on the web. The app marks that diagram with an amber globe. Amber is the app’s colour for “someone outside can read this”, and the globe appears nowhere else. Getting the link shows where it sits in the app.

Getting the link

If the diagram is not in a space yet, the app asks before it files it into one.

To take it back, right-click the row and choose Stop showing. The globe goes away, and every page that embeds the diagram shows a short placeholder card in its place.

Putting it in your docs

Paste the link on a line of its own inside a fenced code block tagged dgmo. This is the whole thing, backticks included, and it works unchanged in Obsidian and in every docs-site plugin below:

```dgmo
https://online.diagrammo.app/d/dgm_01M3PG3DQ6S89W7ZFM5Z06J1CD
```

Once you know the diagram’s id, there is a shorter spelling that does the same job:

```dgmo
live-link dgm_01M3PG3DQ6S89W7ZFM5Z06J1CD
```

Every place it works

On a docs site, a reader who arrives between builds is told the page is behind; see the refresh check. Notion is not tested yet: it embeds links through the same service Confluence uses, so we expect it to work.

This is the other side of showing a diagram on the web — somebody shows it, and your docs site embeds it by id. For diagrams whose source lives in your own repository, see diagrams in your repo.

What happens at build time

Your build fetches the diagram’s source once per id, renders it exactly like a pasted diagram, and writes what it got into .dgmo/references/ in your repository.

That directory is meant to be committed, and the reason matters. A cache in node_modules would make a clean CI checkout hit the network for every diagram on every build, which would turn our availability into your build’s success. With the cache in your repo, the worst case is a page that is quietly a little stale, and the change shows up as a reviewable diff in a pull request.

It holds source, not rendered markup. Rendering is deterministic and your site pins its renderer version, so the source plus that pin reproduces the same bytes without hundreds of kilobytes of generated markup churning in every diff.

sequence What a live-link fence does at build time

Your build is an actor

[Diagrammo Cloud]
  API

Your build -reads the fence-> Reference cache
if the id is not cached, and the network is available
  Your build -fetch this diagram's source-> API
  API -the source, as it is now-> Your build
  Your build -writes it into .dgmo/references/-> Reference cache
else
  Reference cache -the source it already has-> Your build
Your build -draws the diagram into the page-> Your site

When a fetch goes wrong

Two rows are deliberate. A diagram id that has never resolved fails the build, because it can only be a typo, it is yours, and it is one line away from where it was made — rendering a placeholder there would ship a broken embed and call it a warning. And once an author stops showing a diagram, the placeholder is what you get, never the cached copy: stale-but-still-published is fine, stale-after-revoked is publishing something somebody took back.

Building without network access

If your CI runner has no egress, commit the cache from a build that does, then set:

dgmo({
  liveLink: { offline: true },
})

The build then reads only what is in your repository and never reaches for the network.

Turning live links off

Live links resolve by default. If you would rather your build never fetched anything:

// astro.config.mjs — or the equivalent in your wrapper
dgmo({
  liveLink: { enabled: false },
})

With that set, a live-link fence renders a small card naming the diagram and linking through to it, and your build logs a warning naming the file and line. Your readers see the card; nothing is fetched, at build time or in their browser.

That card carries a Show this diagram here link. Removing the option above is what bakes the diagram into the page instead.

The refresh check, and your CSP

A built page also carries a small client script that checks, once the page is idle, whether the diagram has moved since your last build — so a reader who arrives between builds is told the page is behind rather than shown something stale without comment. Almost always it hasn’t moved, and the check costs one edge-cached request. It notices by default; it does not re-render, because re-rendering means shipping the whole renderer to your readers.

If your site sets a Content-Security-Policy it must allow connect-src https://api.diagrammo.app. Without it the diagram still renders — it was baked at build time — but it will never notice a change, and nothing on the page can tell you so, because the report would be blocked too. This is the one thing to get right before shipping live links.

What is not sent

Resolving a live link is a read of one shown diagram’s source by id. Nothing about your site, your repository or your readers is sent — not a page URL, not a referrer you control, not an identifier of any kind. Only diagrams shown on the web are readable at all: there is no token to configure and no allowlist to maintain.

Where to go next

• Embedding in Your Docs — the two things a fence can carry, and which to pick
• Showing a Diagram on the Web — getting the id a live-link fence needs
• Spaces — where a diagram lives before it can be shown
• Diagrams in Your Repo — keeping .dgmo files in version control