Standalone assets and release guardrails

The Mermaid system does more than replace code fences with a diagram image. It emits theme-specific SVG assets and stable metadata. Readers receive static diagrams, while the build receives stable asset URLs that it can reuse without claiming a measured speed result.

Standalone SVG assets use cache-addressed URLs.

The light asset and dark asset let the Open Diagram link target the current theme. The cache key includes renderer version and source content, so output-changing renderer updates can create new immutable URLs.

These assets are emitted during astro:build:generated by emitAssets(). The pipeline records used diagrams as it resolves them, then writes only the assets that appear in the built site.

SVG image assets are best for keeping article HTML compact while preserving no-JS readability. Standalone SVG is also useful for opening a diagram outside the article column, inspecting it at full browser width, and giving future builds a production cache target.

The standalone asset is also a static file like any other build output. Cloudflare can serve it from the edge. The article does not need to call a renderer when a reader opens the diagram in a new tab.

The article contains static SVG images for no-JS reading. The runtime popover uses the same emitted assets when a reader expands the diagram. The standalone cached SVG remains available as a full-page or new-tab view.

Those three surfaces share the same source diagram but serve different reading moments. The article image supports ordinary reading. The expanded popover supports closer inspection without leaving the page. The standalone asset supports full-tab viewing and cache reuse.

The runtime shell does not need to render Mermaid or manipulate SVG internals. It updates the Open link to match the current theme while the page and popover both display emitted SVG assets.

The Sätteri plugin emits a small MermaidDiagramWrapper component with asset URLs, stable ID, cache key, and diagram type. The component renders light and dark SVG images in the article and popover. CSS chooses the visible image from the current data-theme.

This keeps the final HTML compact. Large SVG trees stay in _app/mermaid/, where they can be cached independently and opened directly. It also removes the need for post-build page CSS extraction or runtime SVG cloning.

The renderer creates SVG. The transform creates article-ready nodes. The wrapper turns prepared metadata into light and dark images for the page and popover.

RENDERER_VERSION is part of the Mermaid cache key. When emitted SVG output changes for the same source diagram, changing the renderer version creates new asset URLs.

That version is a build contract. The site uses immutable asset URLs for Mermaid output, so the URL must change when the output bytes need to change. Source content handles most changes automatically. Renderer changes need the explicit version input.

The same idea appears in other static asset systems. A stable URL is useful only when the bytes behind it are meant to stay stable. When the bytes change, the address should change too.

This system checks several reuse layers. It can read memory, disk, and remote production assets before requesting a render, then emit standalone SVG files with input-derived names. Those mechanisms avoid known work, but the repository contains no comparative build timing that would support a speed claim.

The discipline is architectural rather than procedural. Cache keys include source and renderer version. Standalone assets include both light and dark variants. Runtime expansion uses existing SVG assets instead of asking for a second render.

Those choices make Mermaid feel like a native part of the static publication system. A diagram starts as MDX text, becomes SVG during the build, and reaches readers as normal site output.

Each Mermaid fence creates more than one useful output. The article SVG image sits inside the page. The light standalone SVG supports direct viewing in light mode. The dark standalone SVG supports direct viewing in dark mode. The wrapper carries data attributes that let the runtime choose the right Open link.

This small asset graph is why Mermaid is handled by an integration instead of by a one-line markdown plugin. The site needs more than rendered SVG. It needs the rendered SVG to participate in routing, theming, static assets, runtime links, and page optimization.

The graph stays manageable because every output comes from the same source diagram and cache key. The build can reason about the diagram as one unit even though it emits multiple artifacts.

Standalone assets need to look right outside the article page. They cannot rely on the article’s surrounding CSS or data-theme wrapper. That is why emitted assets receive background treatment and theme CSS appropriate to the file.

The light asset is the default no-JS Open link. The dark asset is available through runtime link switching. Both are static files under the built asset directory. A reader can open them directly, and Cloudflare can serve them like any other asset.

This is especially useful for dense diagrams. Article images keep the page readable. Standalone assets give readers a larger direct view without requiring a client-side render.

Cache keys are not only a build performance detail. They influence what readers receive. If a diagram source changes, the output URL changes. If the renderer version changes, the output URL changes. If nothing changes, the same asset can be reused.

That makes the reader experience stable. The browser and edge can cache unchanged diagrams confidently. Updated diagrams get new addresses. The article can link to the exact asset generated for its current source.

This is how static assets should behave. The URL represents a specific build product.

Mermaid assets are treated like first-class publication output. Article SVG images serve the page. Standalone SVG serves direct inspection. Cache keys and renderer versions keep asset URLs honest.

That asset discipline is what lets Mermaid diagrams feel immediate in the article while still supporting theme-aware direct viewing.

The light SVG image is the main no-JS path. It sits in the article HTML and remains readable without runtime code. The light standalone asset gives the Open link a valid destination even before the Mermaid shell updates the link for the current theme.

This means JavaScript is not required for diagram access. JavaScript improves the link target and popover experience, but the article already contains the diagram image. That is the same progressive enhancement rule used across the site.

The asset system is therefore part of accessibility as well as performance. Diagrams are content, and content should be present in the static output.

The runtime shell relies on asset metadata produced by the build. The wrapper stores light and dark standalone URLs. The shell reads those URLs and changes the Open link when html[data-theme] changes. The popover displays the same theme-specific SVG assets as the article wrapper.

Runtime code is small because the build prepared the assets and attributes. The browser does not need to discover where dark SVG files live or regenerate diagram CSS. It only reads what the integration placed in the page.

This is a clean handoff. Build emits artifacts. Runtime connects them to the current document state.

The emitted SVG files are also documentation of the build. A developer can inspect dist/_app/mermaid/ and see the generated assets that correspond to article diagrams. The filenames carry stable IDs and cache keys. Light and dark variants sit beside each other.

That visibility matters for a custom integration. The output is not hidden inside a remote renderer or a browser runtime. It is a static artifact that can be inspected as part of the built site.