Markata’s shared backend rendering pipeline publishes finished SVG assets, with no visualization engine running in the reader’s browser.
Availability:
excalidrawfences 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):
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.
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
widthandheight. 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).