sketch

README

sketch

tuios.dev/sketch draws Mermaid diagrams as SVG, in pure Go.

It is a port of pele, the Mermaid renderer by kepano of Obsidian, under the MIT licence. The layout, the shapes, the safety rules and the test corpus are pele's work. The port follows pele v1.6.0, commit 458322a5b8abb1ae57ddf127c32017ab9fb14a92. LICENSE has the notice of pele and of the port. raster/fonts/NOTICE has the licences of the fonts that sketch/raster draws text in: Arimo (SIL Open Font License 1.1) and Go Mono.

Status

It draws flowcharts, sequence diagrams, state diagrams, class diagrams, ER diagrams, pie charts, mindmaps and gantt charts. Each other diagram type gives an error with the code unsupported-diagram until its port is done.

The output is the same as the output of pele, byte for byte. The test suite compares each diagram with an SVG that pele drew from the same source.

Type	Goldens that match
flowchart	114/114
sequence	38/38
state	22/22
class	38/38
er	25/25
pie	2/2
mindmap	13/13
gantt	11/11

Use

svg, err := sketch.Render("flowchart LR\n  A --> B\n", sketch.RenderOptions{})
if err != nil {
	// err is an *sketch.Error with a code: syntax, semantic, limit or unsupported-diagram.
}
os.WriteFile("out.svg", []byte(svg.Data), 0o644)

Text

tuios.dev/sketch/text draws flowcharts and sequence diagrams with box-drawing characters, for a terminal that shows no pictures. It takes the layout that sketch works out for the SVG and maps it to cells. The labels stay real text.

d, _ := sketch.Parse(src, sketch.ParseOptions{})
lines, err := text.Draw(d, text.Options{Cols: 100})

text.ErrTooWide says the drawing does not fit the columns. The package first asks pele for a narrower layout, which turns a flowchart that runs across to run down. A drawing past text.MaxCells gives text.ErrTooLarge. Every character a terminal acts on, such as ESC in a label, is written as U+FFFD.

Layout of the code

Each Go file is the port of one pele file. The header of the file names it. The Go files keep the names, the functions and the comments of pele, so that a change upstream maps to a change here.

Folder	pele folder
.	src/core.ts, src/detect.ts, src/preprocess.ts
internal/types	src/types.ts, src/errors.ts
internal/text	src/text
internal/svg	src/svg
internal/layout	src/layout
internal/util	src/util
internal/diagrams/...	src/diagrams/...
internal/js	none: JavaScript semantics the port needs

scripts/upstream.sh lists the pele commits after the pin and the files that each commit changes.

Limits

The limits of pele apply. The source can have 50,000 characters. A flowchart can have 5,000 edges. The SVG can have 4,000,000 characters. A host can set lower limits in RenderOptions.

Tests

go test ./...

TestGolden draws the 522 sources of the pele documentation corpus. It shows how many match for each type. It fails when a diagram of a ported type does not match.

Documentation

Overview

Package sketch draws Mermaid diagrams as SVG. It is a Go port of pele (github.com/obsidianmd/pele), which draws them without a browser.

Index

• Constants
• func Supports(src string) bool
• type Config
• type Diagram
  • func Parse(src string, opt ParseOptions) (d *Diagram, err error)
  • func (d *Diagram) Layout(options RenderOptions) (l *Layout, err error)
  • func (d *Diagram) RenderSVG(options RenderOptions) (out SVG, err error)
• type Error
• type ErrorCode
• type ErrorInfo
• type Layout
• type LinkInfo
• type NamedTheme
  • func Themes() []NamedTheme
• type ParseOptions
• type RenderOptions
• type SVG
  • func Render(src string, options RenderOptions) (out SVG, err error)
• type TextMeasurer
• type Theme
  • func ThemeNamed(name string) (*Theme, bool)
• type Type
  • func Detect(src string) (typ Type, ok bool)

Constants

const (
	CodeUnsupported = types.CodeUnsupported
	CodeSyntax      = types.CodeSyntax
	CodeSemantic    = types.CodeSemantic
	CodeLimit       = types.CodeLimit
)

const DefaultLimit = 50000

DefaultLimit is the longest source in characters: Mermaid's default maxTextSize.

const DefaultMaxEdges = 5000

DefaultMaxEdges is the most edges a flowchart can have. Mermaid stops at 500. Pele draws 5,000 edges in tens of milliseconds, and `A & B --> C & D` multiplies: without a limit, a few kilobytes of source ask for millions of edges.

const DefaultOutputLimit = 4_000_000

DefaultOutputLimit is the longest SVG in characters. Mermaid has no limit on its output. A source within the limit can still describe a drawing of many megabytes, which would stall the page it is put into.

Functions

func Supports

func Supports(src string) bool

Supports reports whether the text is a diagram of a type sketch draws.

Types

type Config

type Config = types.Config

type Diagram

type Diagram struct {
	Type Type
	// contains filtered or unexported fields
}

Diagram is diagram text that parsed. RenderSVG draws it.

func Parse

func Parse(src string, opt ParseOptions) (d *Diagram, err error)

Parse reads diagram text.

func (*Diagram) Layout

func (d *Diagram) Layout(options RenderOptions) (l *Layout, err error)

Layout draws the diagram and returns its geometry. Types without geometry yet give a Layout with nothing in it.

func (*Diagram) RenderSVG

func (d *Diagram) RenderSVG(options RenderOptions) (out SVG, err error)

RenderSVG draws a parsed diagram.

type Error

type Error = types.PeleError

Error is what Parse and Render return for text they cannot draw.

type ErrorCode

type ErrorCode = types.PeleErrorCode

ErrorCode says what kind of problem an Error is.

type ErrorInfo

type ErrorInfo = types.ErrorInfo

ErrorInfo is where in the source an Error is, and the diagram type.

type Layout

type Layout = types.Geometry

Layout is the geometry a renderer worked out for a diagram, in SVG units: boxes, routes and label lines. It is not part of pele. sketch/text draws it with box-drawing characters.

type LinkInfo

type LinkInfo = types.LinkInfo

LinkInfo is a link the diagram draws.

type NamedTheme

type NamedTheme struct {
	// Name is the key: lower case, words joined with "-".
	Name string
	// Title is the name for people, such as "Rosé Pine".
	Title string
	// Dark says the background is dark.
	Dark  bool
	Theme Theme
}

NamedTheme is a theme with the name a user types for it.

func Themes

func Themes() []NamedTheme

Themes lists the named themes: pele's own first, then terminal themes.

type ParseOptions

type ParseOptions struct {
	Limit    int
	MaxEdges int
	Config   Config
}

ParseOptions are the options read when the text is parsed.

type RenderOptions

type RenderOptions = types.RenderOptions

RenderOptions are pele's render options. A nil pointer is an option left unset.

type SVG

type SVG struct {
	Type   Type
	Data   string
	Width  float64
	Height float64
	Links  []LinkInfo
}

SVG is a drawn diagram.

func Render

func Render(src string, options RenderOptions) (out SVG, err error)

Render parses and draws diagram text.

type TextMeasurer

type TextMeasurer = text.TextMeasurer

TextMeasurer gives the width of text. The default is a table of Arial advances, which gives the same output as pele.

type Theme

type Theme = types.Theme

Theme sets the colours, fonts and radius of a diagram through pele's --pele-* tokens.

func ThemeNamed

func ThemeNamed(name string) (*Theme, bool)

ThemeNamed finds a named theme. Case, spaces and "_" do not matter.

type Type

type Type = types.DiagramType

Type names a kind of diagram, as Mermaid does: "flowchart", "sequence" and so on.

func Detect

func Detect(src string) (typ Type, ok bool)

Detect gives the type of diagram the text describes.