svg.Render is one way to draw a diagram. This guide is for the other way: drawing a scene.Scene with your own renderer, in a window, an image or a PDF, in your own fonts and theme.
The steps are:
- Lay the source out with
mermaid.Layout, measuring text with your renderer's fonts. - Draw the scene's items in order: each item's paths, then its lines of text.
- Settle colors with a
scene.Palettewhen you draw, not when you lay out.
mermaid/example_test.go does all three in one short file, and go test runs it.
A diagram's boxes are sized to their labels, so text must be measured the way your renderer will set it. Pass a scene.Measurer in mermaid.Options:
type Measurer interface {
Measure(s string, f scene.Font) scene.Metrics
}Metrics.Widthis the advance width ofs. Measure it with the same font, size, weight and fallback fonts you draw with; a measurer that disagrees with the renderer gives text that overflows or floats in its box.Metrics.AscentandDescentare the font's, not the string's: return the same values for every string of onescene.Font, the empty string included. sumi asks for them with"". If they followed the glyphs of each string, labels of the same font would differ in height.- A
scene.Fontnames no typeface. Map it to yours:Sizein DIPs,Boldto a bold weight,Italicto an italic style, andMonoto a monospace family. - A nil measurer measures as Arial does, which suits SVG viewed in a browser, not a native renderer with another font.
Layout calls Measure for every label and for every word it wraps, in a few fonts. If measuring is slow in your renderer, cache what stays the same for a font, such as its ascent and descent.
A scene's coordinates are DIPs (one CSS pixel), with the origin at the top left and y pointing down. Its content lies between (0, 0) and (Width, Height).
Draw Scene.Items in order. For each item, draw its Paths and then its Texts, so labels lie on their shapes.
A path is a list of segments:
Op |
Points | Draw |
|---|---|---|
MoveTo |
Pts[0] |
start a subpath |
LineTo |
Pts[0] |
a line |
QuadTo |
Pts[0] control, Pts[1] end |
a quadratic curve |
CubeTo |
Pts[0], Pts[1] controls, Pts[2] end |
a cubic curve |
Close |
none | a line back to the subpath's start |
Fill the path, then stroke it. The stroke's ends and corners are round. Stroke.Dash lists dash and gap lengths in turn, starting at the path's start; nil is a solid line. Circles and rounded corners are already cubic curves, so a renderer needs no arc command.
Each scene.Line in a scene.Text is placed: X is where it starts and Baseline is its baseline, in the text's Font. Lines are already broken and aligned; draw each one as it is, without wrapping or aligning it again.
Many renderers place text by its top. Move such a line up by your font's ascent, the same ascent your measurer returns.
A paint is either a theme token (Paint.Token) or a color the diagram's author wrote (Paint.Color, when the token is scene.None). Resolve paints when you draw:
if c, ok := palette.Resolve(path.Fill); ok {
// fill with c
}Resolve returns false when there is nothing to paint: the zero paint, a transparent color, or a token missing from the palette.
scene.Lightandscene.Darkare sumi's palettes. Pick one when you draw; switching themes needs no new layout. Author colors stay as written in both.- To match your app's theme, clone a palette (
maps.Clone) and change the colors you want. The tokens are listed inscene/paint.go. scene.Backgroundis the canvas under the diagram. Edge labels sit on patches of it, and a sequence diagram writes its message numbers in it. Paint it in your view's background color, so the patches blend into the page.
Most diagrams are as wide as what they draw. To show one in a narrower view, scale it down uniformly: scale = view width / Scene.Width, and the height follows. Scaling it up past its size enlarges the text past the font size it was measured in, so cap the scale at 1.
A gantt diagram is the exception: it fills the width you give it in Options.Width, as Mermaid fills its element. Pass the width of the place it will be shown in; 0 lays it out 1200 wide. Other diagrams ignore Width.
Layout costs much more than drawing; flowcharts, state, class and ER diagrams run a full graph layout. Lay a diagram out when its source changes and draw the cached scene on every frame. A cache key needs everything the layout depends on:
- the source;
- the fonts the measurer uses;
Options.Width, for gantt diagrams.
A theme change is not on the list. A gantt diagram also reads time.Now for its today line and time.Local for its dates, so the same source laid out on another day, or in another time zone, can differ.
mermaid.Layout returns a *mermaid.Error for a source it cannot read, with the 1-based Line and Col of the problem:
s, err := mermaid.Layout(src, opts)
var e *mermaid.Error
if errors.As(err, &e) {
// A problem at e.Line and e.Col. e.IsUnsupported() reports Mermaid
// that sumi does not draw yet, rather than a mistake in the source.
} else if err != nil {
// Some other failure; show err.
}Show the user something useful instead of an empty space. For example, show the source as code and put the error under it. A scene can also be empty, such as a sequence diagram with no messages; check that Width and Height are above 0 before you scale by them.
Jun, a terminal workspace for macOS, draws Mermaid code blocks in its Markdown view with sumi. internal/app/render_mermaid.go covers each part of this guide: a measurer that uses the window's font shaping, paths and text compiled once into paint calls, the background token painted in the window's background, scaling to the page, and a gantt diagram laid out at the reading width.