Markata’s shared backend rendering pipeline publishes finished SVG assets, with no visualization engine running in the reader’s browser.

Availability: excalidraw fences render to static SVG in native Go builds. D2 and Vega-Lite fences are not supported. Mermaid and Chart.js keep their existing syntax and behavior.

What the foundation provides #

A backend renderer produces SVG bytes from a request. The common package then checks bounded SVG output, derives intrinsic dimensions, assigns a SHA-256-based filename, publishes the asset and emits normal HTML for a figure:

source + palette + font + renderer/version + options
       |
       v
backend Renderer.RenderSVG(ctx, request)
       |
       v
Pipeline (in-process cache and concurrent coalescing)
       |
       v
NewSVGAsset -> Publish(outputDir, asset)
       |
       v
<figure><img src="/assets/visualizations/<sha256>.svg"
             width="960" height="540" alt="..."></figure>

The filename depends on the exact SVG bytes; renderer cache identity also includes the renderer version, theme content hash, and effective options. Repeated assets can be reused by the browser or a CDN.

Integrate a backend in Go #

An adapter implements this interface (shown here for reference, not as a working D2 integration):

go
type Renderer interface {
    ID() string
    Version() string
    RenderSVG(context.Context, visualizations.Request) ([]byte, error)
}

Use visualizations.Pipeline.Compile(ctx, backend, request) for a rendered Asset. visualizations.Publish(outputDir, asset) writes a final static asset; visualizations.FigureHTML(asset, alt, caption, aboveFold) returns escaped markup with an explicit image width and height. A site hosted at a path prefix can use FigureHTMLWithBasePath to project the asset URL below that prefix. Markata derives the prefix from the path in the configured site URL.

The request must include all layout-affecting inputs, especially theme and font contents. Renderers must obey context cancellation and return actionable errors for unsupported syntax, oversized SVG output, or unavailable layout dependencies.

Terminalbash
go test ./pkg/visualizations/...
go test -race ./pkg/visualizations/...
go vet ./pkg/visualizations/...

Why the constraints matter #

  • No layout shift from unknown image dimensions: the figure includes intrinsic width and height. Responsive site CSS still has to preserve the intended image aspect ratio.
  • No visualization JavaScript on the published page: the output is a normal external SVG image, not a browser chart/canvas library.
  • Smaller repeat views: a fingerprinted path enables stable cache identities, but Brotli/gzip and appropriate response headers remain hosting responsibilities.
  • Bounded processing: one SVG has a 4 MiB uncompressed size limit, and the in-process cache holds up to 128 assets or 32 MiB.
  • Clear trust boundary: the XML checks reject many active/remote constructs but are not a complete SVG sanitizer, and do not guarantee a fully offline page. Author-supplied images and linked resources still need a separate output audit.

The current restrictions also reject some legitimate SVG features such as hyperlinks, embedded images, animation, and foreignObject. Excalidraw currently reports linked elements and embedded images as unsupported. Large embedded fonts and complex SVG paths can still increase network and browser-paint cost.

Excalidraw SVGs follow the site’s configured light or dark fallback mode at build time. Standalone rendering defaults to dark when no site configuration is supplied.

The Excalidraw auto mode uses a matching SVG artifact generated by the Go workbench when the author applies a scene. It does not launch a renderer. A missing or stale artifact stops the build with an actionable error. Select mode = "chromium" explicitly to use the browser compatibility renderer. Chromium mode embeds only font files listed in Markata’s local Excalidraw font manifest. Other external CSS resources remain blocked by SVG validation. Node and Rust backends are not advertised until they meet the compatibility and packaging checks in the renderer comparison report.

What comes next #

D2 is the next intended backend adapter, followed by Vega-Lite through vl-convert, once each meets compatibility and performance checks. The shared standalone renderer keeps schema v1 and returns Excalidraw SVG as a data URI; it does not add an asset kind to the manifest.

Mermaid and Chart.js remain available alongside Excalidraw. See the Excalidraw guide, Markdown guide, accessible Chart.js figures, and renderer interoperability contract.

For exact technical invariants, see spec/spec/STATIC_VISUALIZATIONS.md (after this PR merges).