Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

sirene

sirene is a local WYSIWYG editor and viewer for Mermaid, PlantUML, and Graphviz DOT diagrams, with SVG, PNG, and terminal ASCII output. It is one Rust binary, and renders offline without a browser, Node, or Java.

$ printf 'flowchart LR\n  A[Start] --> B{Ok?} -->|yes| C[Done]\n' | sirene ascii
┌───────┐    ╱─────╲       ┌──────┐
│ Start ├───►│ Ok? ├──yes─►│ Done │
└───────┘    ╲─────╱       └──────┘
  • sirene FILE opens an editor window: the source on the left, a live drawing on the right. Edits on either side are written to the source as ordinary text edits.
  • sirene svg, sirene png, and sirene ascii render a diagram file, a Markdown file’s diagram blocks, or stdin without opening a window, and can watch files for changes. svg and png also render directories of diagrams and watch for new files.
  • The parser keeps every byte of the source, so the editor never reformats a file. Diagnostics point at a line and column, and a diagram with errors is still drawn.

Diagrams

Mermaid:

Other Mermaid diagram types are reported as unsupported. See Supported syntax for what is read and how it differs from Mermaid.

PlantUML (@startuml and the other @start kinds): sequence, activity, class, object, state, use case, component, deployment, timing, network, mindmap, WBS, gantt, JSON, YAML, EBNF, regular expression, Chen ER, chronology, and file tree diagrams.

Graphviz DOT (digraph and graph): records, HTML table labels, clusters, and ports.

Start with Install and the Quickstart.

Install

Install script (Linux and macOS)

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/jaemk/sirene/main/bin/install.sh | sh

It downloads the release binary for this platform, checks it against the release’s SHA256SUMS, and installs it to ~/.local/bin. It reads these environment variables:

VariableDefaultMeaning
SIRENE_VERSIONthe latest releasethe version to install, e.g. 0.2.0
SIRENE_INSTALL_DIR~/.local/binwhere to put sirene
SIRENE_TARGETthis platform’s, musl on Linuxthe release target triple

The verified binary is staged in the install directory, then renamed into place. A failed copy keeps the existing binary; a symlink at sirene is replaced without changing its target. A directory at that path, including a symlink to a directory, is refused.

On Linux the default is the static musl build, which runs on any distribution but has no GUI. For the editor, install the glibc build, which needs the system’s X11 or Wayland and Vulkan libraries:

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/jaemk/sirene/main/bin/install.sh | SIRENE_TARGET=x86_64-unknown-linux-gnu sh

(aarch64-unknown-linux-gnu on ARM.)

Homebrew (macOS and Linux)

brew tap jaemk/sirene https://github.com/jaemk/sirene
brew trust jaemk/sirene
brew install sirene          # the binary
brew install --cask sirene   # macOS: Sirene.app, with `sirene` linked onto the PATH

The repo is not named homebrew-sirene, so the tap needs its clone URL. Install one of the formula or the cask, not both: each puts sirene on the PATH. The app is not signed, so macOS asks before the first launch.

Cargo

cargo install sirene                          # with the editor
cargo install sirene --no-default-features    # the command line only

Building the editor on Linux needs the XCB, xkbcommon, Wayland, fontconfig, and Vulkan development packages, e.g. on Debian or Ubuntu:

sudo apt-get install libxcb1-dev libxkbcommon-dev libxkbcommon-x11-dev libwayland-dev \
  libfontconfig1-dev libfreetype-dev libvulkan-dev

A build without the default gui feature does not link any of these; sirene with no command then prints error: built without the GUI; see sirene --help.

Release binaries

Each release has binaries for Linux (musl and glibc, x86_64 and aarch64), macOS (x86_64 and aarch64), a universal Sirene.app zip, and SHA256SUMS.

Quickstart

Write a flowchart:

flowchart LR
    A[Start] --> B{Ok?}
    B -->|yes| C[Done]
    B -->|no| D[Retry] --> B
the drawing of the mermaid source above

Save it as diagram.mmd, then:

sirene ascii diagram.mmd     # print it in the terminal
sirene svg diagram.mmd -o diagram.svg
sirene png diagram.mmd       # writes diagram.png
sirene diagram.mmd           # open it in the editor

sirene with no file opens a new document with a starter flowchart.

In the editor

  • Type in the source pane; the drawing follows as you type.
  • Click a node to select it, double-click (or press enter) to edit its label.
  • Drag from one node to another to connect them.
  • Press secondary-shift-n to add a node after the selected one. Secondary is Cmd on macOS and Ctrl elsewhere.
  • Press backspace to delete the selection, secondary-z to undo.
  • Secondary-s saves.

Every change made in the drawing is an ordinary text edit to the source, so comments, spacing, and statement order are kept. See The editor.

Keeping images up to date

sirene png --watch docs/

writes a .png beside each diagram file (.mmd, .puml, .dot, and the other extensions) under docs/, then writes it again each time one changes. See Command line.

Other languages

PlantUML and Graphviz DOT files render the same way, with the drawing read-only in the editor:

@startuml
Alice -> Bob : hello
Bob --> Alice : hi
@enduml
the drawing of the plantuml source above
sirene ascii hello.puml
printf 'digraph { a -> b -> c }\n' | sirene ascii

See PlantUML and Graphviz DOT.

Playground

Draws Mermaid, PlantUML, or Graphviz DOT source in the browser as you type, with sirene-core built for WebAssembly. The page’s address keeps the source, so a link to it opens the same diagram. The edit button on any diagram in these docs does the same for that diagram.

Command line

sirene [FILE...]              open each FILE in the editor, or a new document
sirene ascii [FILE|-]         print a diagram, or a Markdown file's diagrams, as text
sirene svg [FILE|DIR|-]       print or write SVG
sirene png [FILE|DIR|-]       write PNG
sirene check [FILE|DIR|-]...  print diagnostics only
sirene update                 replace sirene with the latest release

svg, png, ascii, and check never open a window, and work in a build without the GUI. With -, they read stdin; svg, png, and ascii also read stdin with no FILE.

Languages

A diagram’s language comes from its file extension (.mmd and .mermaid Mermaid, .dot and .gv Graphviz DOT, .puml, .plantuml, .pu, and .iuml PlantUML) or its Markdown block’s name (mermaid, dot, graphviz, plantuml, puml). Stdin and other files are DOT when they start with a DOT graph header, PlantUML when they have an @start line, and Mermaid otherwise. --lang mermaid|dot|plantuml, before or after the command, reads every diagram as that language:

printf 'digraph { a -> b }\n' | sirene ascii --lang dot

Opening files

sirene a.mmd b.mmd opens a window for each file; sirene alone opens a new document with a starter flowchart. A FILE named like a command needs a path prefix (sirene ./ascii). A FILE that does not exist and looks like a mistyped command is refused:

$ sirene acsii
error: no file or command named 'acsii'; did you mean 'sirene ascii'? (to open a new file with that name, use './acsii')

This exits with status 2, and no window opens.

sirene ascii

Prints the diagram with box-drawing characters. --charset ascii uses only ASCII (+, -, |, >), and writes stereotypes as <<interface>> rather than «interface». A Markdown file prints each diagram block, with a blank line between them.

$ printf 'flowchart TD\n  A --> B\n' | sirene ascii --charset ascii
+---+
| A |
+-+-+
  |
  v
+---+
| B |
+---+

--width N exits 1 with an error when a drawing is wider than N columns, still printing it, e.g. to keep drawings in a README within 80 columns:

$ sirene ascii --width 80 README.md

--markdown reads stdin, or a file of any name, as Markdown; sirene check --markdown does the same:

$ git show HEAD:README.md | sirene check --markdown -

sirene svg

Prints a standalone SVG document. --theme light|dark picks the colors (default light), and -o, --output PATH writes to PATH instead of stdout (-o - is stdout for a single diagram). Directory and Markdown inputs write one image per diagram and refuse -o - with exit status 2.

sirene png

Writes a PNG, with text drawn in the embedded Noto Sans faces so images are the same on every machine.

OptionMeaning
-o, --output PATHwhere to write (- is stdout for a single diagram); default FILE with .png, or stdout when reading stdin
--theme light|darkthe colors (default light)
--quality draft|normal|finethe detail (default fine); large drawings are shrunk to fit
--scale Npixels per diagram unit, instead of --quality

sirene refuses to write a PNG to a terminal, or to overwrite the input file. Directory and Markdown inputs refuse -o - with exit status 2.

Directories

sirene svg DIR and sirene png DIR render every diagram file (by the extensions above, in any case) under DIR, skipping hidden entries and symlinked directories. Each output is written beside its diagram, or with -o OUTDIR at the same relative path under OUTDIR:

sirene png docs/                     # docs/a.mmd -> docs/a.png
sirene svg docs/ -o site/diagrams/   # docs/x/b.mmd -> site/diagrams/x/b.svg

One file’s errors fail the run without stopping the others. When two diagrams would write the same output (a.mmd beside a.mermaid), the first in path order wins and the other is reported. On macOS and Windows, output paths compare without regard to case, so A.mmd and a.mmd also collide. Output directory symlinks are resolved when checking collisions. An output that would replace any input, including the target of an input symlink, is skipped and reported.

Markdown files

sirene svg FILE.md and sirene png FILE.md (also .markdown) render each mermaid, dot, graphviz, plantuml, or puml code block to STEM-N.svg or STEM-N.png beside the file, N counting blocks from 1; -o OUTDIR writes them there instead. Blocks inside blockquotes and list items count, and the name may be in any case or in braces ({.mermaid}, {mermaid}).

The Markdown file is not changed unless --link is given. --link adds an image link on the line after each rendered, closed block, and only when that line is not already the link, so running it again changes nothing. When a new block shifts the numbering, the old ![diagram N](...) line is replaced. The link is relative to the Markdown file (../img/guide-1.svg for sirene svg docs/guide.md -o img --link). The blocks themselves are never changed or removed. An unclosed block is still rendered, but no image link is inserted for it.

$ sirene svg guide.md --link
wrote guide-1.svg
wrote guide-2.svg
guide.md:15:8: error: expected a node after the edge
wrote guide-3.svg
linked the images in guide.md
```mermaid
flowchart LR
  A[Write] --> B[Render]
```
![diagram 1](guide-1.svg)

Diagnostic positions are lines and columns in the Markdown file.

sirene check

Prints diagnostics without rendering, for diagram files, directories (every diagram file under them), Markdown files (each diagram block), or stdin. It checks every FILE and exits 1 if any has an error, so it fits a pre-commit hook or a CI step:

$ sirene check guide.md docs/
guide.md:15:8: error: expected a node after the edge

--json prints the diagnostics to stdout as one JSON array, for editors and CI annotations:

$ sirene check --json guide.md
[
  {"file":"guide.md","line":15,"column":8,"severity":"error","message":"expected a node after the edge"}
]

--markdown reads stdin and files of any name as Markdown.

sirene update

Replaces the running binary with the latest release, or the one --to VERSION names, after asking (--yes skips the question). --check only reports. The download is the same sirene-VERSION-TARGET.tar.gz the install script uses, for the running build’s target, so a GUI build stays a GUI build. Before anything is replaced it is checked against the release’s SHA256SUMS and against a signature by the project’s release key, which is built into sirene.

$ sirene update --check
update available: 0.6.0 -> 0.6.1 (target x86_64-unknown-linux-gnu)

It never downgrades. A sirene installed by Homebrew or cargo install is refused with the command that updates it (brew upgrade sirene, brew upgrade --cask sirene, or cargo install sirene). GH_TOKEN or GITHUB_TOKEN authenticates the requests when set. With both --check and --to, sirene compares versions locally; it does not check whether the requested release or its archive exists.

Watching

-w, --watch renders, then renders again each input that changes (and in a directory, each diagram that appears) until interrupted. A watched Markdown file is rendered again when it changes:

$ sirene png --watch docs/
watching docs/ (Ctrl-C to stop)
wrote docs/a.png

Diagnostics and exit status

Problems are printed to stderr as NAME:LINE:COL: error: MESSAGE (or warning:), with LINE and COL counting from 1. The diagram is still drawn when there are errors. The exit status is 1 when there is an error (in the diagram, or reading or writing a file) and 0 otherwise. Input is read as UTF-8; UTF-16 or other text is an error that says so (exit 1). Each input file or stdin stream is limited to 64 MiB (67,108,864 bytes); larger inputs are refused with exit status 1. For a Markdown input, the limit applies to the whole file, not each diagram block.

$ printf 'flowchart TD\n  A -->\n' | sirene ascii
<stdin>:2:8: error: expected a node after the edge
┌───┐
│ A │
└───┘

Verbose output

-v, --verbose, before or after the command, prints each step (reading, parsing, layout, rendering, writing, and in the editor opening, reloading, and saving files) with timings to stderr:

$ sirene -v svg diagram.mmd -o diagram.svg
[     0.0ms] DEBUG sirene: sirene 0.6.0 (linux, x86_64): ...
[     0.1ms] DEBUG sirene: rendering 1 file(s)
[     0.1ms] DEBUG sirene: reading diagram.mmd
[     0.2ms] DEBUG sirene: read diagram.mmd: 23 bytes
[     0.4ms] DEBUG sirene_core::flowchart: parsed 23 bytes, 2 lines; 0 syntax diagnostics
[     0.5ms] DEBUG sirene_core::flowchart: lowered 2 nodes, 1 edges, 0 subgraphs, 0 class definitions; 0 diagnostics
[     0.5ms] DEBUG sirene: read as a flowchart
[     0.5ms] DEBUG sirene: parsed and lowered in 357.7µs
[     0.7ms] DEBUG sirene_core::layout: laid out 2 nodes, 0 clusters, 1 edges (1 routed) in 34x114 cells, 147.4µs
[     0.8ms] DEBUG sirene_core::scene::paint: drew a 65x145 scene of 6 elements
[     0.9ms] DEBUG sirene: rendered 731 bytes in 327.9µs
[     0.9ms] DEBUG sirene: writing diagram.svg
[     1.0ms] DEBUG sirene: exit with success

Repeat the flag (-vv) for trace logging. For GUI launches and scripts, logging can also be enabled through the environment:

SIRENE_LOG=debug sirene diagram.mmd
SIRENE_LOG=sirene_core=trace,sirene_gui=debug sirene diagram.mmd

SIRENE_LOG takes precedence over RUST_LOG. Comma-separated directives accept off, error, warn, info, debug, or trace, optionally prefixed by a module name and =. The most specific module filter wins. Verbose flags override the general environment level but keep explicit module filters. General levels apply to sirene’s own crates; an explicit module filter can enable a dependency. Invalid configuration prints an error and exits 2. Logs go to stderr, leaving rendered stdout unchanged. No extra logs are printed without flags or environment configuration. Operational errors include their underlying causes.

Trace logging of sirene_core::profile prints how long each stage of drawing took (reading, layout ordering, edge routing, text or image output):

SIRENE_LOG=off,sirene_core::profile=trace sirene ascii diagram.mmd > /dev/null

The editor

sirene FILE opens a window with the source on the left and a live drawing on the right. Secondary below is Cmd on macOS and Ctrl elsewhere. Every action is also in the menus: the menu bar on macOS, a bar at the top of each window elsewhere. Keys lists them all.

Source and drawing

  • Every change to the source redraws the diagram. Errors and warnings are underlined in the source and the first one is shown in the status bar, with the zoom.
  • Secondary-e shows or hides the source pane; the divider between the panes drags.
  • Click the drawing to give it the keyboard. It shows a frame in the accent color while it has it; keys such as enter, backspace, the arrows, and tab go to the drawing only then.

Editing on the drawing

Each change on the drawing is written to the source as one ordinary text edit: comments, spacing, and statement order are kept, and secondary-z undoes it.

  • Select: click a node or edge; shift-click adds or removes. Escape or a click on empty space clears the selection. Selecting one item highlights its source.
  • Rename: double-click an item, or press enter with one selected, to edit its label in place. <br> is a line break. Enter applies, escape cancels. An empty edge label removes it.
  • Add: secondary-shift-n adds a node labeled New node, linked from the selected node when there is one, and opens its label. Double-click empty space to add a node there.
  • Shape bar: the buttons at the top left of the drawing add a node of that shape, linked from the selected node when there is one.
  • Connect: drag from one node to another (or to itself). Drag from a node to empty space to add a new node linked from it.
  • Delete: backspace or delete removes the selection, with the edges that touch removed nodes. A chain such as A --> B --> C that loses its middle is split, and class, style, click, and linkStyle statements are updated to match.

New nodes get the first unused id of A to Z, then n1, n2, …, and are appended at the end of the document (or of the subgraph they were added in).

The right-click menu

Right-click the drawing for a menu of what applies to the selection, or to what is under the pointer:

  • Nodes: Shape, Add Node Before or After, Connect To and Connect From any other node, and the layout hints below.
  • Edges: Line (solid, thick, dotted, invisible), Arrows (at either end, both, none, or a circle or cross head), Reverse, Longer and Shorter, Move Earlier and Move Later.
  • A subgraph: Add Node inside it, its Direction, Ungroup.
  • Empty space: Add Node, the diagram’s Direction, Select All, Fit Window.
  • Rename and Delete, for the selection.

With several items selected, the menu applies to all of them. An item that would change nothing is disabled with the reason after it, such as Move Earlier (nothing before it to swap with); from a key, the status bar says Can't move earlier: ... instead.

Layout hints

Mermaid has no positions, so sirene changes the layout through the source:

  • Direction sets flowchart TD, LR, and so on, or a subgraph’s direction line.
  • Group (secondary-g) puts the selected nodes in a new subgraph; Ungroup removes one and keeps its contents. An edge to the subgraph then goes to each of its members (A & B --> C).
  • Move To moves a node into another subgraph, or out to the top level. Dragging a node onto a subgraph does the same. A statement such as A --> B moves with the node, and B keeps a mention in the subgraph it was in.
  • Keep Together adds an invisible ~~~ edge between two nodes, which places them next to each other.
  • Move Earlier and Move Later (alt-up, alt-down) swap a statement with its neighbor; the layout follows statement order. Edge linkStyle numbers are updated to match.

Styles

View > Show or Hide Styles (secondary-i) opens a panel listing the document’s classes:

  • Check a class to give it to the selected nodes, uncheck to take it away.
  • New Class defines a class with a light fill and a blue stroke, gives it to the selected nodes, and opens it for editing.
  • Edit shows a class’s fill, stroke, and text color pickers, the stroke width, and solid or dashed lines.

The panel writes classDef and class statements, so one change restyles every node with that class.

With edges selected, an Edge section sets their line color, label color, width, and dashes. It writes one linkStyle N ... per edge, replacing any other linkStyle that named it (except linkStyle default).

Moving around

  • Scroll or drag empty space to pan; the arrow keys pan by a step, shift for further.
  • Secondary-scroll zooms. Secondary-= and secondary– zoom in and out, secondary-0 is 100%, secondary-9 fits the window, secondary-8 fits the selection.
  • Tab and shift-tab step through the nodes in source order.
  • A drawing larger than the window is zoomed to fit when it is first shown.

Files

  • Secondary-s saves, secondary-shift-s saves as. A save replaces the file through a temporary file, keeping its permissions and owner, and a symlink stays a symlink.
  • The window title says (edited) while there are unsaved changes, and closing or quitting asks whether to save them.
  • A file changed on disk is reloaded when there are no unsaved edits. Otherwise the status bar says so; Reload (secondary-r) asks before discarding the edits, and Save asks before overwriting the newer file.
  • File > Open Recent lists the last 10 files.

Markdown files

sirene notes.md opens a Markdown file’s diagram code blocks (mermaid, plantuml, puml, dot, or graphviz) one at a time. The source pane shows the current block’s code, and every edit, typed or made on the drawing, is written back into that block; the rest of the file is not touched. Save writes the whole file.

  • The status bar shows Diagram N of M (line L) with buttons for the previous and next block; secondary-shift-] and secondary-shift-[ do the same.
  • In a file with no diagram blocks, the first edit adds one at the end, named for the language typed (mermaid, plantuml, or dot).
  • Save As to a diagram file writes the current block on its own, and Save As of a diagram to a Markdown file writes it in a block named for its language.
  • Export suggests notes-N.png, the name sirene png notes.md gives block N.

Export

  • File > Export as PNG (secondary-shift-e) and Export as SVG write the drawing in the window’s colors, as sirene png and sirene svg would.
  • Secondary-shift-c copies the drawing to the clipboard as a PNG.

Appearance

View > Appearance follows the system’s light or dark mode by default, or forces Light or Dark for every window. See Settings.

Keys

Secondary is Cmd on macOS and Ctrl elsewhere. Keys marked “drawing” act only while the drawing has the keyboard (click it first); while the source pane or a label field has it, Undo, Redo, and Select All act on that text instead.

Files and windows

KeysAction
secondary-nNew document
secondary-oOpen
secondary-sSave
secondary-shift-sSave As
secondary-rReload from disk
secondary-shift-eExport as PNG
secondary-shift-cCopy the drawing as an image
secondary-wClose the window
secondary-qQuit
secondary-eShow or hide the source pane
secondary-iShow or hide the styles panel
secondary-shift-]Next diagram block of a Markdown file
secondary-shift-[Previous diagram block of a Markdown file

Editing

KeysAction
secondary-shift-nAdd a node, linked from the selected node
enter (drawing)Edit the selected item’s label
backspace, delete (drawing)Delete the selection
escape (drawing)Clear the selection
secondary-zUndo
secondary-shift-zRedo
secondary-aSelect every node and edge (drawing), or all text
tab, shift-tab (drawing)Select the next or previous node
secondary-g (drawing)Group the selected nodes in a subgraph
alt-up, alt-down (drawing)Move the selected statement earlier or later

View

KeysAction
secondary-= or secondary-+Zoom in
secondary–Zoom out
secondary-0Actual size
secondary-9Fit the window
secondary-8Fit the selection
arrows (drawing)Pan; shift for further
secondary-scrollZoom

Mouse

GestureAction
clickSelect a node or edge, or clear the selection on empty space
shift-clickAdd to or remove from the selection
double-clickEdit a label; on empty space, add a node
right-clickThe menu for the item under the pointer or the selection
drag from a node to a nodeConnect them
drag from a node to empty spaceAdd a node linked from it
drag a node onto a subgraphMove it into the subgraph
drag empty space, or scrollPan

Settings

The editor keeps its settings in a settings file of key = value lines:

PlatformPath
Linux and others$XDG_CONFIG_HOME/sirene/settings, else ~/.config/sirene/settings
macOS~/Library/Application Support/sirene/settings
Windows%APPDATA%\sirene\settings

SIRENE_CONFIG_DIR overrides the directory.

KeyValuesSet by
appearancesystem, light, darkView > Appearance
windowWxH, e.g. 1200x760the size of the last window closed
sourceshown, hiddenshowing or hiding the source pane
source_widthpixelsdragging the divider
recenta path, up to 10 lines, most recent firstopening and saving files

The file is written by the editor; editing it by hand works, but unknown keys and bad values are skipped, and a missing or unreadable file gives the defaults. New windows open at the saved size (1200x760 at first), cascading from the active window, with the source pane as it last was.

Agents

The sirene repo is a mind source. It offers one skill, sirene:render, that teaches coding agents to check and render Mermaid, PlantUML, and DOT diagrams with the command line: checking a diagram for errors, printing it as text, writing PNG or SVG, and rendering the diagram blocks of a Markdown file.

mind meld jaemk/sirene

The skill needs sirene on the PATH (see Install); the agent asks before installing it. It never opens the editor, and never changes a Markdown file unless asked to add image links. Its text is at skills/render/SKILL.md.

Rust library

sirene-core reads, lays out, and draws diagrams without the CLI, with the same output as sirene ascii, sirene svg, and sirene png. API reference: docs.rs/sirene-core.

[dependencies]
sirene-core = { version = "0.6", features = ["png"] }  # `png` only for PNG output
use std::path::Path;
use sirene_core::diagram::{self, Lang};
use sirene_core::scene::Theme;

fn main() -> sirene_core::Result<()> {
    let path = Path::new("login.mmd");
    // UTF-8 of at most 64 MiB, with errors naming the file.
    let src = &sirene_core::source::read(path)?;
    // The extension picks DOT (`.dot`, `.gv`) or PlantUML (`.puml`, ...); otherwise the
    // source's header picks the diagram type.
    let lowered = diagram::lower_as(src, Lang::of_path(path));
    for d in &lowered.diagnostics {
        let (line, col) = d.line_col(src);
        eprintln!("{line}:{col}: {}", d.message);
    }

    // What `sirene ascii`, `sirene svg`, and `sirene png` write.
    println!("{}", lowered.ascii(&Default::default())?);
    let svg: String = lowered.svg(&Theme::LIGHT)?;
    let png: Vec<u8> = lowered.png(&Theme::DARK, sirene_core::scene::png::Quality::Fine, None)?;

    // Each diagram block of a Markdown file.
    let md = "# Notes\n\n```dot\ndigraph { a -> b }\n```\n";
    for block in sirene_core::markdown::mermaid_blocks(md) {
        let svg = diagram::lower_as(&block.code, Some(block.lang)).svg(&Theme::DARK)?;
    }
    Ok(())
}
  • Reading never fails: problems are Diagnostics with byte ranges and a Severity (an error is what Mermaid would refuse to draw). The diagram is still drawn. diagnostic::LineIndex finds the lines and columns of many diagnostics in one pass.
  • A diagram’s own theme and themeVariables apply over the theme passed in.
  • Lowered::scene gives the display list for other renderers, with text measured by any scene::TextMetrics.
  • scene::png (feature png) draws text with embedded Noto Sans faces, so images are the same on every machine.
  • flowchart::parse and flowchart::edit give the flowchart syntax tree and turn changes to the diagram into minimal source edits; the editor uses them.
  • Errors are sirene_core::Error; error.report() formats the full chain of causes.
  • sirene-core builds for wasm32-unknown-unknown. For web pages, use the prebuilt module instead: see Web pages.

Web pages

sirene-core built for WebAssembly draws Mermaid, PlantUML, and DOT in the browser, with no server and no other dependencies. The playground and the edit button on each diagram in these docs use it.

Files

From npm, as @jaemk/sirene:

npm install @jaemk/sirene

It is published by the release workflow with npm provenance (npm audit signatures checks it). jsDelivr and unpkg serve the package’s files to any page, so a page can load them without hosting them:

<script src="https://cdn.jsdelivr.net/npm/@jaemk/sirene@X.Y.Z/sirene-wasm.js"></script>
<script>
  SireneWasm.load(fetch("https://cdn.jsdelivr.net/npm/@jaemk/sirene@X.Y.Z/sirene.wasm"))
    .then(function (sirene) { sirene.renderAll(document, { theme: "light" }); });
</script>

Or from GitHub: each release after 0.6.0 attaches sirene-wasm-X.Y.Z.tar.gz. Both hold:

File
sirene.wasmthe module (about 2.7 MB, 0.9 MB gzipped); SVG and ASCII output
sirene-wasm.jsthe loader: a plain script that sets window.SireneWasm
LICENSE-MIT, LICENSE-APACHE, THIRD-PARTY-NOTICESlicenses
curl -fsSLO https://github.com/jaemk/sirene/releases/download/vX.Y.Z/sirene-wasm-X.Y.Z.tar.gz
tar -xzf sirene-wasm-X.Y.Z.tar.gz

SHA256SUMS in the release lists its checksum, and gh attestation verify sirene-wasm-X.Y.Z.tar.gz --repo jaemk/sirene checks its build provenance.

Serve both files from your own site. GitHub release downloads can’t be loaded from a page directly (no CORS headers), and browsers do not fetch WebAssembly from file:// pages.

Drawing a page’s diagram blocks

renderAll replaces each diagram block with an <img class="sirene-diagram"> of its SVG:

<pre><code class="language-mermaid">flowchart LR
  A --&gt; B</code></pre>

<script src="sirene-wasm.js"></script>
<script>
  SireneWasm.load(fetch("sirene.wasm")).then(function (sirene) {
    sirene.renderAll(document, { theme: "light" });
  });
</script>

It draws <pre><code class="language-X"> blocks, as Markdown renderers write them, for mermaid, plantuml, puml, dot, and graphviz, and mermaid.js’s <pre class="mermaid"> and <div class="mermaid">. A block it cannot draw stays as source, with the error in its data-sirene-error attribute; renderAll returns { drawn, failed }. Note that a block with errors in its source is still drawn, as sirene svg draws it.

examples/web/index.html is a complete page.

Drawing one source

const sirene = await SireneWasm.load(fetch("sirene.wasm"));
const r = sirene.render(source, { format: "svg", lang: "mermaid", theme: "dark" });
if (r.ok) {
  // r.output: the SVG document as a string ("ascii": the `sirene ascii` text)
}
for (const d of r.diagnostics) {
  console.log(`${d.severity}: ${d.line}:${d.column}: ${d.message}`);
}
OptionValues
formatsvg (default), ascii
langdetect (default, from the source’s header), mermaid, plantuml or puml, dot or graphviz
themedark (default), light; a diagram’s own theme setting applies over it

render is synchronous. A source that crashes the module returns ok: false and the next call starts a fresh instance. The module imports nothing, so it also runs outside a browser, e.g. Node:

const SireneWasm = require("@jaemk/sirene");
const wasm = fs.readFileSync(require.resolve("@jaemk/sirene/sirene.wasm"));
const sirene = await SireneWasm.load(wasm);

Loaded as a plain script, sirene-wasm.js sets globalThis.SireneWasm instead.

A page with a Content Security Policy needs script-src 'wasm-unsafe-eval' to compile the module and img-src data: for renderAll’s images.

Supported syntax

sirene reads Mermaid’s flowchart syntax (flowchart, graph, and flowchart-elk). This page lists what is read and where sirene differs from Mermaid. The other types sirene draws have pages of their own.

Header and direction

flowchart LR

The direction is TB (or TD), BT, LR, or RL, and defaults to TB. direction inside a subgraph sets that subgraph’s direction; outside one it has no effect and is a warning.

Frontmatter (--- … ---) is read for title:, which is drawn above the diagram, and for config.theme and config.themeVariables. Theme settings in %%{init}%% directives are also read and override the frontmatter; see Themes. Other lines starting with %% are comments.

Nodes and labels

A
B[Label]
C["Quoted: (any) [characters]"]
D["`**Bold** and *italic*`"]
E[Two<br>lines]
F:::important
  • A node is created where it is first mentioned, and a node without a label shows its id.
  • A later mention with a shape replaces the shape and label.
  • "..." labels may hold any character but "; use #quot; for it. Entity codes such as #amp;, #lt;, and #9829; are decoded, as are HTML entities such as &nbsp;. Named codes are the HTML 4 set (#copy;, &hearts;, &rarr;, &mdash;, …).
  • "`...`" labels are markdown: **bold**, __bold__, *italic*, and _italic_.
  • <br> is a line break. In a label that is not markdown, <b>/<strong> and <i>/<em> pairs are bold and italic, and other HTML tags (<span>, <u>, …) are dropped. Font Awesome icons (fa:fa-car) are not drawn: they stay as text.
  • :::name adds a class.
  • end is reserved and cannot be a node id.

See Shapes for the shape delimiters and @{ shape: ... }.

Edges

A --> B
A --- B
A -.-> B
A ==> B
A ~~~ B
A <--> B
A --x B
A --o B
A -->|label| B
A -- label --> B
A ----> B
A & B --> C & D
A --> B --> C
A e1@--> B
StrokeForms
normal---, -->
thick===, ==>
dotted-.-, -.->
invisible~~~
  • >, x, and o are arrowheads; a start marker (<, x, o) makes the edge two-headed. Mermaid drops a start marker that does not match the end; sirene keeps it.
  • Extra -, =, or . make an edge longer (up to 10), which puts its ends further apart.
  • A & B --> C & D adds an edge from each node on the left to each on the right.
  • An inline label (-- text -->) must be on one line. Mermaid allows a line break there; sirene does not, so a missing closing stroke cannot swallow the statements after it.
  • e1@ gives the edge an id, for e1@{ ... }, class, and style.

Subgraphs

subgraph api [API]
    direction LR
    A --> B
end
subgraph "Data stores"
    db[(Postgres)]
end
api --> db

A subgraph’s members are the nodes mentioned in its body. A node already in an earlier subgraph stays there. Edges may start or end at a subgraph. An edge between a subgraph and a node inside it is not drawn and is a warning. A subgraph with a direction keeps it when an edge links to the subgraph itself; an edge between a node inside it and a node outside drops it, as in Mermaid.

api@{ view: collapsed } after a subgraph’s end draws it as one node: its title over a dashed rule and three dots. Edges to anything inside it end at that node, and edges wholly inside it are not drawn.

Styling

classDef warm fill:#fdf2e3,stroke:#c77d1a,color:#5a3200
class A,B warm
C:::warm
style D fill:#e8f1fb,stroke-width:2px,stroke-dasharray:4 2
linkStyle 0 stroke:#d33,stroke-width:3px
linkStyle default stroke:#888

These properties are drawn: fill, stroke, stroke-width, stroke-dasharray, and color (text). Others are ignored. Colors may be #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), rgba(), a CSS color name, none, or transparent. Declarations are split at commas, so escape the commas inside a function: style A fill:rgb(255\,0\,0). \, is a literal comma.

Precedence, lowest first: classDef default (nodes) or linkStyle default (edges), then the item’s classes in order, then its own style or linkStyle. A filled node without a color keeps a text color that reads on its fill.

style and class also accept an edge id, which Mermaid does not.

Metadata

A@{ shape: cyl, label: "Orders" }
e1@{ animate: true }

An @{ ... } block is a flat mapping of key: value entries, separated by commas on one line. Over several lines, each entry starts a line, so a comma is text, and label: | takes the indented lines after it as a multi-line label:

B@{
  label: |
    Hello, world
    second line
}

Nodes read shape and label; edges read animate, animation, and curve, and linkStyle reads interpolate. Those four are parsed but not drawn. Other keys are kept but have no effect.

Click and accessibility

click, accTitle, and accDescr are parsed and checked; click has no effect in the editor.

Errors

An error is confined to its statement: the rest of the diagram is still read and drawn. sirene reports an error where Mermaid would fail to render, and a warning where Mermaid would silently ignore or guess, such as a class naming a node that does not exist.

Shapes

A node’s shape comes from the delimiters around its label, or from @{ shape: NAME }, which takes every Mermaid shape name and alias:

flowchart LR
    A[Process] --> B{Decision} --> C[(Database)]
    D@{ shape: doc, label: "Report" }
    E[Queue]@{ shape: das }
the drawing of the mermaid source above

When a node has both, @{ shape } wins, and the bracket text stays its label.

NameDelimitersAliases
rectA[text]proc, process, rectangle
roundedA(text)event
stadiumA([text])terminal, pill
fr-rectA[[text]]subprocess, subproc, framed-rectangle, subroutine
cylA[(text)]db, database, cylinder
circleA((text))circ
dbl-circA(((text)))double-circle
(ellipse)A(-text-)
oddA>text]
diamA{text}decision, diamond, question
hexA{{text}}hexagon, prepare
lean-rA[/text/]lean-right, in-out
lean-lA[\text\]lean-left, out-in
trap-bA[/text\]priority, trapezoid-bottom, trapezoid
trap-tA[\text/]manual, trapezoid-top, inv-trapezoid
datastoredata-store
folderdirectory
bucket
console
browser
person
bang
cloud
text
notch-rectcard, notched-rectangle
lin-rectlined-rectangle, lined-process, lin-proc, shaded-process
sm-circstart, small-circle
fr-circstop, framed-circle
forkjoin
hourglasscollate
bracecomment, brace-l
brace-r
braces
boltcom-link, lightning-bolt
docdocument
delayhalf-rounded-rectangle
h-cyldas, horizontal-cylinder
lin-cyldisk, lined-cylinder
curv-trapcurved-trapezoid, display
div-rectdiv-proc, divided-rectangle, divided-process
triextract, triangle
win-paneinternal-storage, window-pane
f-circjunction, filled-circle
notch-pentloop-limit, notched-pentagon
flip-trimanual-file, flipped-triangle
sl-rectmanual-input, sloped-rectangle
docsdocuments, st-doc, stacked-document
st-rectprocs, processes, stacked-rectangle
bow-rectstored-data, bow-tie-rectangle
cross-circsummary, crossed-circle
tag-doctagged-document
tag-recttagged-rectangle, tag-proc, tagged-process
flagpaper-tape
lin-doclined-document

Every shape has its own outline, as Mermaid draws it. Small, filled, and framed circles, forks, hourglasses, and bolts show no label. An unknown name, or one with uppercase letters or _, is an error and leaves the shape unchanged.

The shapes example draws the shapes that have delimiters.

Themes

A diagram can pick one of Mermaid’s themes, and override its colors, in its frontmatter or in an %%{init}%% directive. The diagram’s theme replaces --theme and the editor’s light or dark setting when drawing it as an image.

%%{init: {'theme': 'forest'}}%%
flowchart LR
  A[Start] --> B{Ready?}
  B -->|yes| C[Ship]
the drawing of the mermaid source above

The same in frontmatter, with themeVariables:

---
config:
  theme: base
  themeVariables:
    primaryColor: '#BB2528'
    lineColor: '#F8B229'
    fontSize: 18px
---
flowchart LR
  A --> B
the drawing of the mermaid source above

Themes: default, base, dark, forest, neutral, neo, neo-dark, redux, redux-dark, redux-color, and redux-dark-color. An unknown name is a warning.

themeVariables work as in Mermaid: variables such as primaryColor, primaryBorderColor, primaryTextColor, lineColor, background, mainBkg, nodeBorder, clusterBkg, and edgeLabelBackground feed the colors the theme derives. With no theme, the variables apply to the application’s theme.

A theme also colors pie slices (pie1 to pie12) and the sections of mindmaps, timelines, radar charts, and treemaps (cScale0 to cScale11); set one of those variables to change a single color.

Note that text output is not themed, and other charts (git graphs, gantt charts, journeys, sankey diagrams, XY charts, Venn diagrams) keep sirene’s own colors.

Examples

The diagrams in examples/, drawn by sirene svg --theme dark and sirene ascii when this site was built. Open one in the editor with sirene examples/architecture.mmd.

Architecture

flowchart LR
    user((User)) --> cdn[CDN]
    cdn --> lb{{Load balancer}}

    subgraph app [Application]
        lb --> api1[API server 1] & api2[API server 2]
        api1 & api2 --> queue>Job queue]
        queue --> worker[[Worker]]
    end

    subgraph data [Data]
        db[(Postgres)]
        cache[(Redis)]
        blob[(Object store)]
    end

    api1 & api2 --> db
    api1 & api2 -.-> cache
    worker --> db
    worker --> blob

    classDef store fill:#e8f1fb,stroke:#3b6ea5
    classDef edge fill:#fdf2e3,stroke:#c77d1a
    class db,cache,blob store
    class cdn,lb edge
the drawing of the mermaid source above

Build graph (DOT)

digraph build {
  rankdir=LR;
  node [shape=box, style=rounded];

  subgraph cluster_sources {
    label = "sources";
    style = dashed;
    parser; layout; render;
  }

  subgraph cluster_outputs {
    label = "outputs";
    color = blue;
    svg; png; ascii [label="ASCII"];
  }

  parser -> layout -> render;
  render -> svg;
  render -> png;
  render -> ascii;
  tests [shape=note];
  tests -> parser [style=dotted];
}
the drawing of the dot source above

Checkout (PlantUML)

@startuml
title Checkout
actor Customer
participant "Web Shop" as Shop
participant Payments
database Orders

Customer -> Shop : place order
activate Shop
Shop -> Payments : charge card
alt approved
  Payments --> Shop : receipt
  Shop -> Orders : save order
  Shop --> Customer : confirmation
else declined
  Payments --> Shop : declined
  Shop --> Customer : ask for another card
end
deactivate Shop
@enduml
the drawing of the plantuml source above

CI pipeline

---
title: CI pipeline
---
flowchart LR
    push([Push to a branch]) --> lint[fmt and clippy]
    lint --> test[Tests]
    test --> cov{Coverage at least 98%?}
    cov -->|yes| pr[Ready to merge]
    cov -->|no| fail[[Fail the run]]
    lint -. warnings .-> fail

    subgraph release [Release, on main]
        decide{New version?} -->|yes| build[Build binaries]
        build --> publish[(crates.io)]
        decide -->|no| skip(Nothing to do)
    end

    pr ==> decide

    %% A subgraph's direction applies when no edge crosses its border.
    subgraph checks [Checks run on each push]
        direction TB
        fmt[cargo fmt] --> clippy[cargo clippy] --> tests[cargo test]
    end
the drawing of the mermaid source above

Fulfillment (PlantUML)

@startuml
title Fulfillment
start
:Receive order;
if (In stock?) then (yes)
  :Pick items;
else (no)
  :Order from supplier;
endif
fork
  :Charge card;
fork again
  :Pack box;
end fork
while (More boxes?) is (yes)
  :Label box;
endwhile (no)
:Ship;
note right: tracked
stop
@enduml
the drawing of the plantuml source above

Login

flowchart TD
    %% A sign-in flow with two-factor authentication.
    start([Open the app]) --> session{Signed in?}
    session -->|yes| home[Home screen]
    session -->|no| form[/Email and password/]
    form --> check{Valid?}
    check -->|no| error[Show the error] --> form
    check -->|yes| twofa{Two-factor on?}
    twofa -->|no| home
    twofa -->|yes| code[/Enter the code/]
    code --> verify{Code matches?}
    verify -->|yes| home
    verify -->|no, 3 tries| locked[Lock the account]
    verify -->|no| code
the drawing of the mermaid source above

Order lifecycle

flowchart LR
    %% Edge kinds: solid, thick, dotted, invisible, and arrowheads.
    cart[Cart] --> placed[Placed]
    placed ==>|paid| paid[Paid]
    placed -. timeout .-> cancelled[Cancelled]
    paid --> packed[Packed] --> shipped[Shipped]
    shipped ==> delivered([Delivered])
    shipped --x lost[Lost in transit]
    delivered <-->|exchange| paid
    delivered --o review[Review]
    lost ~~~ cancelled
the drawing of the mermaid source above

Request timing (PlantUML)

@startuml
title Request timing
clock "Clock" as C with period 50
binary "Enable" as EN
robust "Web Browser" as WB
concise "Web User" as WU

WB has Processing, Waiting, Idle

@0
WU is Idle
WB is Idle
EN is low

@100 as :request
WU is Waiting
WB is Processing
EN is high

@300
WB is Waiting

@500
WU is Idle
WB is Idle
EN is low

@:request
WU -> WB : URL
WB@100 <-> @+200 : {200 ms}
highlight 300 to 500 #Gold : waiting
@enduml
the drawing of the plantuml source above

Shapes

flowchart TD
    %% Every node shape.
    rect[Rectangle] --> round(Rounded) --> stadium([Stadium]) --> sub[[Subroutine]]
    cyl[(Cylinder)] --> circle((Circle)) --> dbl(((Double circle))) --> odd>Asymmetric]
    diamond{Diamond} --> hex{{Hexagon}} --> leanR[/Lean right/] --> leanL[\Lean left\]
    trap[/Trapezoid\] --> inv[\Inverted trapezoid/] --> ellipse(-Ellipse-) --> bare
the drawing of the mermaid source above

Shop model (PlantUML)

@startuml
title Shop model
package catalog {
  abstract class Product {
    -id : UUID
    +price() : Money
  }
  class Book extends Product {
    +isbn : String
  }
  interface Shippable
}
enum Status {
  NEW
  PAID
  SHIPPED
}
class Order {
  +status : Status
  --
  +total() : Money
}
Book ..|> Shippable
Order "1" *-- "many" Product : contains >
Order --> Status
@enduml
the drawing of the plantuml source above

Styling

flowchart LR
    %% classDef, class, :::, style, and linkStyle.
    a[Default] --> b[Hot]:::hot --> c[Cold] --> d[Dashed] --> e["`**Markdown** label`"]
    c --> f[Line 1<br>Line 2]

    classDef hot fill:#fde2e1,stroke:#c0392b,stroke-width:2px,color:#7b241c
    classDef cold fill:#e3f2fd,stroke:#1f618d
    class c cold
    style d fill:#fff,stroke:#555,stroke-dasharray: 5 3
    linkStyle 0 stroke:#c0392b,stroke-width:3px
    linkStyle 2 stroke:#1f618d,stroke-dasharray: 4 2
the drawing of the mermaid source above

Sequence diagrams

sirene draws Mermaid sequence diagrams (sequenceDiagram) as images and as text:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
the drawing of the mermaid source above

In the editor a sequence diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
participant A, participant A as Alice, actor Aa box, or a stick figure, at the top and bottom of a lifeline
participant A@{ "type": "database" }boundary, control, entity, database, collections, or queue shapes (boxes in text)
A->>B: texta message; participants not declared are added in order of first mention
->, -->, ->>, -->>, -x, --x, -), --), <<->>, <<-->>solid or dotted lines with no head, a filled head, a cross, an open head, or heads at both ends
A->>A: texta loop back to the same lifeline
A->>+B, B-->>-A, activate A, deactivate Aactivation bars, offset when nested (heavy lifelines in text)
note left of A, note right of A, note over A,Ba note beside or across lifelines
loop, alt/else, opt, par/and, critical/option, breaka frame with its kind and label, and dashed dividers; frames nest
rect COLOR ... enda colored background (a dotted frame in text)
box COLOR Title ... enda group around the participants declared inside; it holds only declarations
create participant B, destroy Ba header where the participant is created, and a cross where its lifeline ends
autonumber, autonumber 10 5, autonumber offa numbered badge on each message (1. before the label in text)
title text, accTitle, accDescrthe title above (frontmatter title too)
<br>, #59;a line break, and entity codes
participant A; participant B; ends a statement as a newline does; write #59; for a literal one

Keywords are matched in any case, so Note over A works.

Messages advance the autonumber counter even while numbering is off. A bare autonumber resumes the current number and step instead of restarting: after autonumber 10 5, one numbered message, autonumber off, and one unnumbered message, a bare autonumber numbers the next message 20. See the forms above to set a new start or step.

Errors

These are errors, and the rest of the diagram is drawn:

  • deactivating a participant that is not active;
  • else, and, or option outside its block;
  • an end with nothing to close, or a block left open;
  • create for a participant already mentioned;
  • an autonumber that is not off or numbers.

A participant still active at the end is a warning.

Not drawn

link, links, properties, and details are warnings and skipped. wrap, par_over (drawn as par), and the sequence config options are ignored.

State diagrams

sirene draws Mermaid state diagrams (stateDiagram and stateDiagram-v2) with the same layout, themes, and outputs as flowcharts:

stateDiagram-v2
  [*] --> Still
  Still --> Moving : push
  Moving --> [*]
the drawing of the mermaid source above

In the editor a state diagram is read-only on the drawing side: select, zoom, export, and copy work, and the source pane edits as usual. Drawing edits say why they are off.

What is read

SyntaxDrawn as
s1, state "Description" as s1, s1 : Descriptiona rounded state; more descriptions add lines
s1 --> s2, s1 --> s2 : labela transition with an arrow, labeled in the middle
[*]a start dot as a source, an end ring as a target, one of each per composite state
state Name { ... }a composite state, titled with its name; nested freely
-- inside a composite stateconcurrent regions, each in a dashed box
state f <<fork>>, <<join>>a bar across the direction of flow
state c <<choice>>a small diamond
note left of s : text, note right of s … end notea note beside the state, joined by a dashed line
direction TB|BT|LR|RLthe diagram’s direction, or a composite state’s
classDef, class s1,s2 name, s1:::name, stylecolors and strokes, as in flowcharts
%% comments, frontmatter title, accTitle, accDescras in flowcharts

A note left of a state sits above it in a left-to-right diagram, and one on the right sits below. A note on a composite state sits beside its box.

Not drawn

These are warnings on the line that has them, and the rest of the diagram is drawn:

  • click
  • floating notes (note "text" as N), which Mermaid parses but does not draw either
  • transitions between two concurrent regions of one composite state
  • other stereotypes, such as <<history>>, which draw as a plain state

Class diagrams

sirene draws Mermaid class diagrams (classDiagram and classDiagram-v2) with the same layout, themes, and outputs as flowcharts:

classDiagram
  class Shape {
    <<interface>>
    +area() double
  }
  class Circle {
    +double r
  }
  Shape <|.. Circle
the drawing of the mermaid source above

In the editor a class diagram is read-only on the drawing side, as state diagrams are.

What is read

SyntaxDrawn as
class A, class A["Label"], class List~T~a box titled A, Label, or List<T>; generics nest (List~List~int~~ is List<List<int>>)
class `Animal Class!` a class name in backticks, which may hold spaces and punctuation
class A { ... }, A : +int idmembers: attributes, then methods (a member with ()
+make()$, +draw()*static members underlined, abstract ones italic
<<interface>> in a body, or <<interface>> A«interface» above the name
<|--, *--, o--, -->, --hollow triangle, filled diamond, hollow diamond, arrow, plain line
..>, ..|>, ..the same, dotted
A --() B, A ()-- Ba lollipop interface: a small circle at the () end
A "1" --> "*" B : labelcardinalities beside each end, the label in the middle
namespace N { ... }a box around the classes declared in it with class
link A "url", click A href "url" "tip"a link, with an optional tooltip and target (_blank)
callback A "fn", click A call fn(args)a callback, as in flowcharts
note for A "text"a note beside the class
note "text"a note on its own
direction, classDef, cssClass "A,B" name, A:::name, styleas in flowcharts

An edge runs from the left class to the right one, so in Super <|-- Sub the superclass is drawn above. Space around the relation is optional (Duck-->Egg), except for an o end: write A o-- B and A --o B.

In ASCII the markers are △ (^), ◆ (*), and ◇ (o), pointing the way the triangle does.

Not drawn

These are warnings, and the rest of the diagram is drawn: styling or a link of a class that does not exist, and a relation or A : member line inside a namespace (Mermaid rejects it).

ER diagrams

sirene draws Mermaid entity relationship diagrams (erDiagram) with the same layout, themes, and outputs as flowcharts:

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER {
    int id PK
    string status
  }
the drawing of the mermaid source above

In the editor an ER diagram is read-only on the drawing side, as state and class diagrams are.

What is read

SyntaxDrawn as
A, "Quoted name", A[Alias], A["Alias"]a box titled with the name or alias
A { type name PK, FK "comment" }one row per attribute, in columns of type, name, keys, and comment
|o, ||, }o, }| (o|, o{, |{ mean the same, on either side)zero or one, exactly one, zero or more, one or more
--a solid line (identifying)
.., .-, -.a dotted line (non-identifying)
one or more to zero or many, only one optionally to 1+, …the same, in words; optionally to is dotted
A ||--o{ B : labelthe label in the middle; it may be quoted
List~T~ in a typeList<T>
direction, classDef, class A,B name, A:::name, styleas in flowcharts

An edge runs from the left entity to the right one. In ASCII the markers are ? (zero or one), 1 (exactly one), * (zero or more), and + (one or more), next to the entity.

Not drawn

Styling of an entity that does not exist is a warning, and the rest of the diagram is drawn.

Git graphs

sirene draws Mermaid git graphs (gitGraph) as images and as text:

gitGraph
  commit id: "init"
  branch develop
  commit id: "feature" tag: "beta"
  checkout main
  commit id: "hotfix"
  merge develop id: "release" tag: "v1.0"
the drawing of the mermaid source above

In images each branch is a lane, left to right by default, with commits in source order. Text always puts one commit per row, as git log --graph does. In the editor a git graph is read-only on the drawing side.

What is read

SyntaxDrawn as
gitGraph, gitGraph LR:, gitGraph TB:, gitGraph BT:lanes left to right, top to bottom, or bottom to top
commita circle on the current branch
commit id: "x"the id x; without one, a stable generated id such as 0-2245cbe
commit type: REVERSE / HIGHLIGHTa crossed circle / a filled square (⊗ / ■ in text)
commit tag: "v1"a tag label ([v1] in text)
branch name, branch name order: 2a new lane starting at the current commit
checkout name, switch namelater commits go on that branch
merge name (with id, tag, type)a ringed merge commit (◉), joined to the merged branch
cherry-pick id: "x" (with parent, tag)a commit tagged cherry-pick:x

msg: is read but not drawn. Lanes are ordered as in Mermaid: main, then branches without order in the order declared, then the others by order.

Errors

Merging a branch into itself or one with no commits, checking out an unknown branch, reusing a commit id or branch name, and cherry-picking a commit that is missing, already on the branch, or a merge without parent: are errors on that line; the rest of the graph is drawn.

Not drawn

gitGraph settings in frontmatter config (showBranches, mainBranchName, and the others) are ignored, and ids are never rotated.

Timelines

sirene draws Mermaid timelines (timeline) as images and as text:

timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : YouTube
    2006 : Twitter
the drawing of the mermaid source above

In the editor a timeline is read-only on the drawing side.

What is read

SyntaxDrawn as
timeline, timeline LR, timeline TDperiods left to right with events below, or top to bottom with events to the right
title textthe title above (frontmatter title too)
2002 : A : Ba period and its events
: C on the next lineanother event for the period above
section namea box over the periods that follow, until the next section
<br>a line break; long text also wraps

A : separates only when followed by a space or the end of the line, so 10:30 : standup is the period 10:30. Each section has its own color; without sections, each period does.

Errors

An event before any period and a section without a name are errors, and an empty event is a warning; the rest of the timeline is drawn.

Colors

Section colors can be overridden with themeVariables.cScale0 to cScale11; see Themes.

Not drawn

disableMulticolor is ignored.

Pie charts

sirene draws Mermaid pie charts (pie) as images and as text:

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
the drawing of the mermaid source above

In the editor a pie chart is read-only on the drawing side.

What is read

SyntaxDrawn as
pieslices largest first, clockwise from the top, with a legend to the right
pie showDataeach value in the legend (Dogs [386]) and in the text form
title textthe title above, also on the header line (pie title Pets); frontmatter title too
"label" : 42.5a slice; single quotes work too

Each slice shows its share as a whole percent. As in Mermaid, a slice under 1% is not drawn (the others fill the circle) but stays in the legend.

Errors

A negative value is an error, and a label given twice is a warning; the slice is skipped and the rest of the chart is drawn.

Colors

Slice colors can be overridden with themeVariables.pie1 to pie12; see Themes.

Not drawn

textPosition is ignored.

Gantt charts

sirene draws Mermaid gantt charts (gantt) as images and as text:

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d
the drawing of the mermaid source above

In the editor a gantt chart is read-only on the drawing side.

Tasks

NAME : DATA, where DATA is comma-separated: optional tags, then END, START, END, or ID, START, END.

PartValues
tagsactive, done, crit, milestone (a diamond), vert (a line across the chart)
STARTa date, or after ID ID... (the latest of their ends); left out, the end of the task before
ENDa date, a duration (3d, 1.5h, 2w, 30m, 10s, 500ms, 1M, 1y), or until ID ID...

Settings

SettingEffect
title, section NAMEthe title, and a group of the tasks that follow
dateFormat FORMAThow dates are written, as dayjs reads them (default YYYY-MM-DD)
axisFormat FORMAThow the axis labels are written, in d3’s % codes (default %Y-%m-%d)
tickInterval 1weekthe axis step: a number and millisecond, second, minute, hour, day, week, or month
excludes weekends, friday, 2014-01-15days a duration skips, shaded grey; a date is matched as written in dateFormat and as YYYY-MM-DD
includes 2014-01-18days never excluded
weekend fridaythe weekend is Friday and Saturday (default saturday: Saturday and Sunday)
weekday mondaythe day weekly ticks fall on (default sunday)
inclusiveEndDatesan END date includes that day
todayMarker off or todayMarker stroke:#0f0,stroke-width:3pxhide or style the line at today
topAxisrepeat the axis above the chart

dateFormat reads strictly: YYYY-MM-DD does not read 2014-1-6. A date that does not match it is read as ISO 8601 (2014-01-06T09:30). Dates have no time zone; today is the current date in UTC.

The formats, tickInterval, topAxis, weekday, and displayMode: compact (tasks of a section share rows when they do not overlap) can also be set in frontmatter or a directive; a setting in the chart wins:

---
config:
  gantt:
    axisFormat: "%b %e"
    displayMode: compact
---
gantt
    ...

Errors

An unknown after or until id, tasks that wait on each other, an id used twice, an unreadable date or duration, a task with no start and no task before it, and an unknown weekday, weekend, or tickInterval are errors; the task or setting is skipped and the rest is drawn. click is a warning and ignored.

Not drawn

Pixel settings (barHeight, fontSize, …) and the theme colors (taskBkgColor, …) are ignored.

Mindmaps

sirene draws Mermaid mindmaps (mindmap) as images and as text:

mindmap
  root((mindmap))
    Origins
      Long history
      Popularisation
    Research
      On effectiveness<br/>and features
      On Automatic creation
    Tools
      Pen and paper
      Mermaid
the drawing of the mermaid source above

In the editor a mindmap is read-only on the drawing side.

What is read

SyntaxDrawn as
indentationthe tree: a node’s parent is the nearest line above it that is indented less
textthe default shape: a box with a line under it
id[text]a square
id(text)a rounded box
id((text))a circle
id)text(a cloud
id))text((a bang
id{{text}}a hexagon
[text], (text), …a shape without an id
id["text"]quoted text, which may hold (, [, and the other delimiters
id["`**bold** *italic*`"]a markdown string, which may span lines
<br>a line break
:::a bclasses on the node above, kept in the model
frontmatter titlethe title above

The root sits in the middle. Its children go down the right side in order until that side holds about half the height, and the rest down the left. Each of the root’s children and everything under it gets its own color, and edges thin with depth. Text wraps at 200 pixels. In text, each node shows its shape’s delimiters.

Errors

A second line indented as little as the root, or less, has no parent: it is an error, and the line is left out. An ::icon(...) or ::: line before the first node is an error.

Not drawn

::icon(...) is read and kept on the node, with a warning, but icon fonts are not drawn. Classes have no effect without CSS, as in Mermaid. The layout is always the two-sided tree; Mermaid’s force-directed cose-bilkent layout is not used.

User journeys

sirene draws Mermaid user journeys (journey) as images and as text:

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me
the drawing of the mermaid source above

In the editor a user journey is read-only on the drawing side.

What is read

SyntaxDrawn as
title textthe title above; frontmatter title too
section namea colored box over its tasks
name: score: actor, actora task box with a dot per actor, and a face below it for the score
accTitle, accDescrkept in the model

A score runs from 1 to 5 and may have a fraction. Faces sit lower for lower scores, and smile above 3, frown below 3, and are level at 3. Actors are listed with their colors at the left. In text, each task has a bar of five steps for its score, rounded.

Errors

A task with no score or a score that is not a number is an error, and the task is skipped. A score outside 1 to 5 is a warning and is drawn at the nearest end. Text after the actors (5: Me: more) is a warning and ignored.

Quadrant charts

sirene draws Mermaid quadrant charts (quadrantChart) as images and as text:

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]
the drawing of the mermaid source above

In the editor a quadrant chart is read-only on the drawing side.

What is read

SyntaxDrawn as
title textthe title above; frontmatter title too
x-axis Low --> Highlabels under the left and right halves; x-axis Low alone is centered
y-axis Low --> Highlabels beside the bottom and top halves; y-axis Low alone is centered
quadrant-1 text to quadrant-4 textlabels at the top of the top right, top left, bottom left, and bottom right quadrants
Name: [x, y]a point, with x and y from 0 to 1
"Name": [x, y]a quoted name, which may hold :
Name: [x, y] radius: 10, color: #f00a point’s own style
Name:::cls: [x, y] and classDef cls color: #f00a style from a class; the point’s own styles win
accTitle, accDescrkept in the model

A point’s styles are radius, color, stroke-color, and stroke-width. A stroke is drawn only with stroke-width. With no points, quadrant labels sit in the middle of their quadrants.

In text, a point is ● with its name beside it. A name that would cross another name, a point, or a middle line is replaced by a key (1, 2, …) listed under the chart.

Errors

A point without a complete [x, y], or with a coordinate that is not a number, is an error, and the point is skipped. A coordinate outside 0 to 1 is a warning and is drawn at the nearest edge. An unknown style, a bad style value, and a class with no classDef are warnings and ignored.

Not drawn

Frontmatter config for quadrantChart (sizes, paddings, font sizes, axis positions) and theme variables are ignored. The x-axis labels are always below the chart and the y-axis labels always left of it.

XY charts

sirene draws Mermaid XY charts (xychart-beta and xychart) as images and as text:

xychart-beta
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
the drawing of the mermaid source above

In the editor an XY chart is read-only on the drawing side.

What is read

SyntaxDrawn as
xychart-beta horizontalcategories down the side and values across
title "text"the title above; frontmatter title too
x-axis "title" [a, "b c"]categories along the x-axis
x-axis "title" 0 --> 10a numeric x-axis, with each series spread evenly across it
y-axis "title" 0 --> 100the value axis’s range; without one it spans the data
bar [1, 2.5, -3]a bar per value, up from the bottom of the value axis
line [1, 2, 3]a line through the values
line "name" [...], bar "name" [...]a named series, listed in the legend
line [540 "PaLM", 65]a label beside a point
accTitle, accDescrkept in the model

A title or name with spaces needs quotes. Without an x-axis, positions are numbered from 1. Series take colors in order and later ones draw over earlier ones, as in Mermaid.

In text, each x position is a row, with a bar per bar series and a marker per line series, scaled across the value axis, whose span is printed under the table.

Errors

A malformed list or range is an error, and its statement is skipped. A range written high to low (10 --> 0) is a warning and turned around. Categories on the y-axis are an error. Values beyond the number of categories are a warning and are not drawn.

Not drawn

Frontmatter config for xyChart (sizes, showDataLabel, showLegend, axis settings) and theme variables such as plotColorPalette are ignored.

Requirement diagrams

sirene draws Mermaid requirement diagrams (requirementDiagram) as images and as text:

requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req
the drawing of the mermaid source above

In the editor a requirement diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
requirement name { ... }a box with «Requirement» above the name and its fields below
functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraintthe same, with that type above the name
id:, text:, risk:, verifymethod:a requirement’s fields
element name { type: ..., docref: ... }a box with «Element» and its type and doc ref
a - satisfies -> b, b <- satisfies - aa dashed arrow from a to b labeled «satisfies»; also copies, derives, verifies, refines, traces
a - contains -> ba solid line from a circle at a
"quoted name"a name or value with :, -, or other punctuation
name:::cls, class a,b cls, classDef, styleclasses and styles, as in flowcharts
direction LRthe layout direction

Keywords, field names, and relationship types match in any case. A risk is shown as Low, Medium, or High, and a verify method as Analysis, Inspection, Test, or Demonstration.

Errors

An unknown relationship type, an unclosed {, and a field without : are errors. A field the type does not have (an element’s id), an unknown risk or verify method, a class or style for an unknown name, a relationship to a name that is never defined (drawn as a plain box), and a second definition of a name (skipped; the first is kept) are warnings.

Not drawn

contains uses a plain circle where Mermaid draws a circle with a plus. Mermaid’s newer look and ELK layout are not used, and markdown in names and values is shown as written.

Kanban boards

sirene draws Mermaid kanban boards (kanban) as images and as text:

kanban
  backlog[Backlog]
    item1[Draft onboarding guide]@{ assigned: 'alex', priority: 'Low' }
    item2["Quoted: card (with brackets)"]
  doing[In Review]
    item3[Fix login timeout]@{
      ticket: BUG-101
      assigned: 'sam'
      priority: 'Very High'
    }
  done[Done]
the drawing of the mermaid source above

In the editor a kanban board is read-only on the drawing side.

What is read

SyntaxDrawn as
a node at the first node’s indenta column, titled by its text
a node indented under a columna card in that column
id[text], [text], text, id["text"]the column’s or card’s text, as in mindmaps
@{ assigned: 'name' }the assignee, at the card’s bottom right
@{ ticket: ID }the ticket, at the card’s bottom left
@{ priority: 'High' }a colored stripe: Very High, High, Low, or Very Low
@{ label: 'text' }the text, in place of the bracketed one
frontmatter titlethe title above
frontmatter config.kanban.ticketBaseUrlkept in the model

Metadata may span lines. In text, a card’s details line shows its priority, ticket, and assignee.

Errors

A node indented less than the first column is an error, and it is left out. An unclosed @{ is an error. Other metadata keys and unknown priorities are warnings and ignored.

Not drawn

::icon(...) and :::classes are read and kept, but not drawn. Tickets are not links.

Packet diagrams

sirene draws Mermaid packet diagrams (packet) as images and as text, in the layout of RFC header diagrams:

packet
title UDP Packet
+16: "Source Port"
+16: "Destination Port"
32-47: "Length"
48-63: "Checksum"
64-95: "Data (variable length)"
the drawing of the mermaid source above

In the editor a packet diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
0-15: "label"a field across bits 0 to 15
106: "URG"a one-bit field
+8: "label"a field of 8 bits after the one before
title text, frontmatter titlethe title above
frontmatter config.packet.bitsPerRowbits per row, 32 by default
frontmatter config.packet.showBits: falseno bit numbers
frontmatter config.packet.bitOrder: descendingeach row with its highest bit on the left
packet-betathe same as packet

A field that crosses the end of a row continues on the next. In text, a label too wide for its box wraps, and a one-bit flag reads down its box.

Errors

Each field must start at the bit after the one before. A field after a gap is an error but is drawn, leaving the gap empty; a field that overlaps the one before is an error and left out. A field that ends before it starts, +0, a field past bit 9999, and a label without quotes are errors.

Not drawn

The other config.packet keys (bitWidth, rowHeight, paddings) and theme variables are ignored.

Radar charts

sirene draws Mermaid radar charts (radar-beta) as images and as text. In text, each axis gets a bar per curve, scaled from the minimum to the maximum:

---
title: "Grades"
---
radar-beta
  axis m["Math"], s["Science"], e["English"]
  axis h["History"], g["Geography"], a["Art"]
  curve a["Alice"]{85, 90, 80, 70, 75, 90}
  curve b["Bob"]{70, 75, 85, 80, 90, 85}

  max 100
  min 0
the drawing of the mermaid source above

In the editor a radar chart is read-only on the drawing side.

What is read

SyntaxDrawn as
axis a["Label"], baxes from the center, the first pointing up and the rest clockwise; an axis without a label shows its id
curve c["Label"]{1, 2, 3}a closed curve with a value per axis, in axis order
curve c{b: 2, a: 1}values by axis id, in any order; the braces may span lines
max 100, min 0the values at the rim and the center; max defaults to the largest value, min to 0
ticks 5the number of rings
graticule circle, graticule polygonround rings, or rings with a corner on each axis
showLegend falseno legend
title text, frontmatter titlethe title above
frontmatter config.radarwidth, height, the four margins, axisScaleFactor, axisLabelFactor, and curveTension

A value outside min to max sits on the center or the rim.

Errors

A curve with fewer values than axes is an error, and the missing values sit at the minimum; extra values are ignored. With keyed values, an id that is not an axis, a repeated id, a value without an id, and a missing axis are errors. A repeated axis id, a max at or under min, and an option with a bad value (graticule square, ticks 0) are errors; a bad config.radar value is a warning.

Colors

Curve colors can be overridden with themeVariables.cScale0 to cScale11; see Themes.

Not drawn

themeVariables.radar is ignored.

Sankey diagrams

sirene draws Mermaid sankey diagrams (sankey-beta) as images and as text. In text, each node lists its outgoing flows, with bars scaled to the largest flow:

---
title: Household budget
config:
  sankey:
    linkColor: source
    nodeAlignment: left
    prefix: "$"
---
sankey
"Salary, net",Budget,4200
Side work,Budget,600
Budget,Rent,1800
Budget,Food,700
Budget,Savings,1200
Budget,"The ""other"" pile",1100
Savings,Index fund,900
Savings,Cash,300
the drawing of the mermaid source above

In the editor a sankey diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
source,target,valuea band from source to target as wide as the value; nodes are made on first use
"a, b",c,1a quoted name may hold ,; "" is a literal "
frontmatter titlethe title above
config.sankey.linkColorgradient (the default), source, target, or a color such as "#a1a1a1"
config.sankey.nodeAlignmentjustify (the default), left, right, or center
config.sankey.showValuesfalse leaves values out of the labels
config.sankey.prefix, suffixtext around each value, e.g. "$" or " TWh"
config.sankeyalso width, height, nodeWidth, and nodePadding

Errors

A row that is not source,target,value, a value that is not a number, and a quoted name not closed on its line are errors. A negative value, a node flowing into itself, and a row that closes a cycle are errors and the row is left out. A bad config.sankey value is a warning.

Not drawn

Theme variables are ignored.

Treemaps

sirene draws Mermaid treemaps (treemap-beta) as images and as text. In text, the items are an outline, largest first, with each value and a bar for its share of the total:

---
config:
  treemap:
    valueFormat: "$,.2f"
    padding: 6
---
treemap-beta
"Housing"
  "Rent": 1800.5
  "Utilities": 210
"Food"
  "Groceries": 640:::big
  "Dining", 1,180
"Savings": 900:::calm
classDef big fill:#f96,stroke:#333,stroke-width:2px
classDef calm fill:#9cf,color:#036
the drawing of the mermaid source above

In the editor a treemap is read-only on the drawing side.

What is read

SyntaxDrawn as
"Name"a section holding the items indented under it
"Name": 10 or "Name", 10a leaf whose area is its value; , and _ in a value are ignored
'Name'single quotes work as well
"Name": 10:::clsa leaf or section styled by classDef cls (fill, stroke, stroke-width, color)
title, frontmatter titlethe title above
accTitle, accDescrread, not drawn
config.treemap.valueFormata d3-format string such as ",.2f", "$,", ".1%", or ".2s"
config.treemap.showValuesfalse leaves values out
config.treemapalso padding, diagramPadding, nodeWidth, and nodeHeight

A section’s value is the sum of its items. Several top-level items are allowed.

Errors

A value that is not a number, a missing value after :, a name not closed on its line, and a line that is not an item, classDef, or title are errors. A section with no items, a class with no classDef, and a bad config.treemap value are warnings.

Colors

Section colors can be overridden with themeVariables.cScale0 to cScale11; see Themes.

Block diagrams

sirene draws Mermaid block diagrams (block-beta) as images and as text. Blocks fill a grid of columns in order; in text the edges are listed below the grid:

block-beta
  columns 3
  a b c
  d:2 e
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/block/valid/ for groups, block arrows, and styles. In the editor a block diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
columns 3, columns autothe columns of the diagram or group; auto (the default) is one row
a, a["Label"], a(("Label")), …a block, with the flowchart shapes
a:2a block 2 columns wide
space, space:2an empty column, or 2
a<["Label"]>(right)a block arrow pointing right, left, up, down, x (both across), or y (both up and down); several directions are allowed
block:id["Title"] … end, block … enda group of blocks with its own columns
a --> b, a -- "text" --- b, ==>, -.->an edge, drawn straight from block to block
classDef, class, stylestyles, on blocks and groups
frontmatter titlethe title above
config.block.paddingthe space between blocks (8)
accTitle, accDescrread, not drawn

Every block in a group is as large as the largest, per column it spans, as in Mermaid. Labels decode entities in both forms, &nbsp; and #nbsp;.

Errors

An unclosed block, an end with nothing to close, columns without a number, a block arrow without directions or with an unknown one, an unclosed shape or quote, and an edge without a block after it are errors. columns 0 and a width of 0 are errors and drawn as 1. A block wider than its group’s columns and a class or style for an unknown id are warnings.

Not drawn

Theme variables are ignored.

Architecture diagrams

sirene draws Mermaid architecture diagrams (architecture-beta) as images and as text. Each edge names the side it leaves and enters by, and that places its ends on a grid; in text a service is a box with its icon name:

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service disk2(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/architecture/valid/ for junctions, arrows, labels, and group edges. In the editor an architecture diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
service id(icon)[Label]a service: its icon with the label below
group id(icon)[Label]a dashed box titled at the top left, with its icon
junction ida point where edges meet
... in groupinside that group; groups nest
a:R -- L:ban edge from a’s right side to b’s left; b is placed right of a
a:R --> L:b, a:R <-- L:b, a:R <--> L:ban edge with arrows
a:R -[label]- L:ban edge with a label
a{group}:R -- L:ban edge from the side of a’s group
align row a b, align column a bthe services kept in one row or column, in order
title, frontmatter titlethe title above
accTitle, accDescrread, not drawn

The icons cloud, database, disk, internet, and server are drawn; any other icon, such as logos:aws-s3, is a question mark.

Errors

A statement that is none of the above, a missing id, side, or edge, and an unclosed (, [, or -[ are errors. An id declared twice, a group that is not declared above, an edge to an unknown id or to a group are errors. {group} on a service outside a group, or on both ends in one group, is a warning and drawn from the service. An align with an unknown id or fewer than two members is a warning.

Not drawn

Icon packs (iconify names) are not loaded, and the layout is a grid rather than Mermaid’s force-directed one. Theme variables are ignored.

C4 diagrams

sirene draws Mermaid C4 diagrams (C4Context, C4Container, C4Component, C4Dynamic, and C4Deployment) as images and as text. Elements fill rows from the left, boundaries go below them, and in text the relations are listed under the drawing:

C4Container
    title Shop
    Person(user, "Customer")
    System_Boundary(shop, "Shop") {
        Container(web, "Web App", "Go", "Serves pages")
        ContainerDb(db, "Database", "Postgres")
    }
    Rel(user, web, "Uses", "HTTPS")
    Rel(web, db, "Reads")
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/c4/valid/ for context, container, and deployment diagrams. In the editor a C4 diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
Person, System, Container, Componenta box with its <<type>>, label, [technology], and description; a person has an icon
...Db, ...Queue (e.g. SystemDb, ContainerQueue)a cylinder, upright or lying down
..._Ext (e.g. Person_Ext, SystemDb_Ext)the external colors
Boundary, Enterprise_Boundary, System_Boundary, Container_Boundarya dashed box titled at the top left with its kind
Deployment_Node, Node, Node_L, Node_Ra solid box titled at the top left
Rel, Rel_U, Rel_D, Rel_L, Rel_R, RelIndexan arrow with its label and [technology]
Rel_Back, BiRelan arrow the other way, or both ways
UpdateElementStyle, UpdateRelStylethe colors given by $bgColor, $fontColor, $borderColor, $textColor, $lineColor
UpdateLayoutConfig$c4ShapeInRow elements and $c4BoundaryInRow boundaries per row
title, frontmatter titlethe title above
accTitle, accDescrread, not drawn

Arguments go by position or by name ($descr="...") and may be quoted.

Errors

A statement that is none of the above, an unclosed string, (, or {, and a stray } are errors. An id declared twice, an element without an alias, and a relation to an unknown id are errors and skipped. A { after an element is a warning and its contents are drawn outside it. A macro that is read but not drawn, such as AddElementTag or Lay_R, and a row count that is not a whole number of at least 1, are warnings.

Not drawn

Tags, sprites, links, relation offsets, and Rel_U/Rel_D/Rel_L/Rel_R directions are ignored, and boundary styles are not drawn. Theme variables are ignored.

ZenUML diagrams

sirene draws ZenUML sequence diagrams (zenuml) as images and as text, the same way it draws sequence diagrams. A call such as A.method() activates A for its body, and a call with no caller comes in from the left:

zenuml
    title Order service
    order = OrderService.create(item) {
        Repo.save(item)
    }
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/zenuml/valid/ for annotators, creations, replies, and fragments. In the editor a ZenUML diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
A, A as Label, "A B"a participant, in order of appearance
@Actor A, @Database A, @Boundary A, @Control A, @Entity A, @Queue A, @Collections Aa participant drawn as that symbol
@Starter(A)A as the caller of calls that name none
A->B: textan async message (an open arrowhead)
@return or @reply before A->B: texta dotted reply
A.method(args), C->A.method(args)a sync call from the current caller (or C), activating A
... { ... } after a callthe statements inside, called from A
x = A.method(), Type x = A.method()a dotted reply x when the call ends
return xa dotted reply x from the call it is inside
new A(args), a = new A()A’s header drawn here, and a <<create>> call
if(c) { … } else if(d) { … } else { … }an alt block with dividers
while(c), for(c), forEach(c), foreach(c), loop(c)a loop block
opt {, par {an opt or par block
try { … } catch(e) { … } finally { … }a try block with dividers
title, frontmatter titlethe title above
// commentread, not drawn

Errors

A statement that is none of the above, an unclosed (, ", or {, a stray }, a . without a method, new without a participant, a fragment without {, and extra text after a statement are errors, and the statement is not drawn. An annotator other than those above is a warning and the participant is drawn as a box. return outside a call, and @return not followed by an async message, are warnings and ignored.

Not drawn

Comments are not drawn above messages, and Markdown in them is not rendered. Participant groups, stereotypes, colors, widths, dividers (==text==), and icon annotators (@EC2, …) are not read.

Info diagrams

sirene draws Mermaid’s info diagram as its own version, where Mermaid draws Mermaid’s:

$ echo info | sirene ascii
sirene v0.2.1

showInfo (after info or on its own line) is read and draws the same. A title line or frontmatter title is drawn above the version. Any other line is an error.

Ishikawa diagrams

sirene draws Mermaid’s ishikawa (fishbone) diagrams (ishikawa-beta) as images and as text. The first line is the effect, and the indented lines under it are its causes:

ishikawa-beta
    Late delivery
    People
        Short staffed
            Holidays
    Methods
    Machines
        Broken scanner
the drawing of the mermaid source above

As an image, the effect sits in a head at the end of a spine, with the causes on bones above and below it. See crates/sirene-core/tests/fixtures/ishikawa/valid/ for more. In the editor an ishikawa diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
the first linethe effect, in the head
a line indented under anothera cause of that line
<br>a line break
%% comment, frontmatter titleread; the title is drawn above

Every line is a label, so there are no errors past the header. The first cause’s indentation is the causes’ level, and a line indented at or left of it is a cause of the effect.

Not drawn

The hand-drawn look and the ishikawa config options are not read.

Venn diagrams

sirene draws Mermaid’s venn diagrams (venn-beta) as images and as text. Each set is a circle, and each union is where circles overlap:

venn-beta
  title "Team overlap"
  set A["Frontend"]:20
    text A1["React"]
    text A2["Design Systems"]
  set B["Backend"]:12
    text B1["API"]
  union A,B["Shared"]:3
    text AB1["OpenAPI"]
  style A fill:#ff6b6b
the drawing of the mermaid source above

As an image, circles are sized and placed the way Mermaid places them. See crates/sirene-core/tests/fixtures/venn/valid/ for more. In the editor a venn diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
set A, set A["Label"]a circle, with its label or id
union A,B["Label"]the overlap of earlier sets, with its label
:N after a set or unionits size (a set’s default is 10)
text A,B id["Label"], or text id indented under a set or uniontext inside the region
style ids fill:..., color:..., stroke:..., stroke-width:..., fill-opacity:...those styles
title, %% comment, frontmatter titleread; the title is drawn above

A union of three or more sets also overlaps each pair of them. A union naming a set not declared before it is an error.

Not drawn

The hand-drawn look, Mermaid 12’s newer default look and theme, and the venn config options are not read.

Wardley maps

sirene draws Mermaid’s Wardley maps (wardley-beta) as images and as text. Components are placed by visibility (up) and evolution (across):

wardley-beta
title Storage Options
anchor App [0.95, 0.70]
component Database [0.40, 0.60]
App -> Database

pipeline Database {
  component "File System" [0.25]
  component "SQL DB" [0.50]
  component "NoSQL" [0.70]
  component "Cloud DB" [0.85]
}
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/wardley/valid/ for more. In the editor a Wardley map is read-only on the drawing side.

What is read

SyntaxDrawn as
anchor Name [visibility, evolution]bold text
component Name [visibility, evolution]a circle with its name
label [x, y] after a componentits name moved by that offset
(build), (buy), (outsource), (market)a shaded ring, or three dots for market
(inertia)a bar right of the component
A -> B, A -.-> B, A +> B, A +<> B, A +'text'> B, ; labellinks, dashed, with arrowheads, labeled
evolve Name 0.8a red arrow to the new evolution
pipeline Name { component X [evolution] }a box of components under its parent
evolution A -> B@0.4 -> C / Dstage names, at positions when given
note, annotation, annotations, accelerator, deacceleratortext, numbered circles with a list, arrows
title, size [w, h], %% commentread; the title is drawn above

Coordinates from 0 to 1 are fractions, and above 1 percentages. A link or evolve naming an unknown component is left out with a warning.

Not drawn

Labels on links and the Visibility axis label stay level instead of turning. The hand-drawn look and the wardley config are not read.

Tree views

sirene draws Mermaid’s tree views (treeView-beta) as images and as text. Entries nest by indentation, or by box-drawing characters as tree prints them:

treeView-beta
    my-project/
        src/
            App.tsx :::highlight icon(logos:react) ## main component
            index.js ## entry point
        .env ## environment variables
        Dockerfile
        package.json
the drawing of the mermaid source above

As an image, the rows are laid out as Mermaid lays them out, under a root /. See crates/sirene-core/tests/fixtures/treeview/valid/ for more. In the editor a tree view is read-only on the drawing side.

What is read

SyntaxDrawn as
name, "name with spaces", 'name'a row, nested under the nearest line indented less
name/a directory, in bold
├── name, └── name, │, and the heavy ┣━━, ┗━━, ┃the same tree, nested by the branch’s column
:::highlighta shaded row
icon(file), icon(folder), icon()that icon, or none
## texta description in italics, lined up right of the labels
frontmatter treeView: rowIndent, paddingX, paddingY, lineThickness, showIconsread
title, %% commentread; Mermaid does not draw the title

Not drawn

Icons from icon packs (icon(logos:react)) are drawn as ?, as Mermaid draws an icon that is not registered. defaultIconPack, filenameIcons, extensionIcons, and the theme variables are not read. In text, icons and highlights are left out.

Use case diagrams

sirene draws Mermaid’s use case diagrams (usecase-beta) as images and as text: actors, use cases, system boundaries, and the relationships between them.

usecase-beta
direction LR
actor Customer
actor Support
systemBoundary Storefront
  Browse("Browse catalogue")
  Checkout("Checkout")
end
systemBoundary Fulfilment
  Track("Track delivery")
end
Customer --> Browse
Customer --> Checkout
Customer --> Track
Support --> Track
Checkout ..> : include Browse
the drawing of the mermaid source above

As an image, actors are stick figures with their names below. See crates/sirene-core/tests/fixtures/usecase/valid/ for more. In the editor a use case diagram is read-only on the drawing side.

What is read

SyntaxDrawn as
actor A, actor A("label"), actor A, Ba stick figure
@{ type: hollow }, @{ type: awesome }a hollow outline, or a filled silhouette
U("label"), U[label], "label", an undeclared endpointan ellipse, or a rectangle for [...]
@{ business: true }the business slash on an actor or ellipse
<<Stereotype>>«Stereotype» above the label
systemBoundary id["title"] ... end, @{ type: package }a box around its members, with a title tab for package
-->, <--, --, --o, o--, --x, x--, with more dashes for a longer edgean association with that marker
-- label --> and the other labelled formsa labelled association
..> : include, ..> : extenda dotted arrow labelled «include» or «extend»
--|>a generalization, with a hollow triangle
A id@--> B, id@{ animate: true }, id@{ animation: fast }an edge that class, style, and metadata can name
note for U "text"a note linked to its actor or use case
json T@{ ... }a table of the object’s keys and values, nested keys as a.b and items[0].name
:::a,b, class a,b c,d, classDef, styleclasses and styles
direction, accTitle, accDescr, %% commentread

Mermaid’s rules (an icon with a non-normal type, include between non-use-cases, a JSON table with a circle or cross marker, and the like) are warnings, and the diagram is still drawn.

Not drawn

Icon actors (@{ icon: "fa:user" }) are drawn as stick figures. Mermaid 12’s redux-color theme, neo look, ELK layout, and the usecase frontmatter config are not used.

Railroad diagrams

sirene draws Mermaid’s railroad diagrams as images and as text: one syntax diagram per grammar rule, written in EBNF (railroad-ebnf-beta), ABNF (railroad-abnf-beta), PEG (railroad-peg-beta), or Mermaid’s constructor notation (railroad-beta).

railroad-peg-beta
# keywords excluded
Identifier <- !Keyword Letter Letter* ;
Keyword <- "if" / "else" / "while" ;
Any <- &Letter . ;
the drawing of the mermaid source above

Terminals are rounded boxes, non-terminals square boxes, and special sequences dotted boxes. Choices branch, optionals get a bypass over the top, and repetition a loop below. See crates/sirene-core/tests/fixtures/railroad/valid/ for more. In the editor a railroad diagram is read-only on the drawing side.

What is read

NotationSyntax
allname = ... ; rules over any number of lines, title, accTitle, accDescr, %% comment
EBNF= or ::=, "t", 't', names, , or juxtaposition, |, [ ], { }, ( ), ?, *, +, A - B, ? special ?, (* *) and /* */ comments
ABNF=, "t", names, /, [ ], ( ), *, 1*, 2*4, 3 repeats, %x41, %x30-39, %x0D.0A numbers, ; comments
PEG<-, "t", 't', names, /, ( ), ?, *, +, & and ! predicates, ., # comments
constructors=, terminal("t"), nonterminal("n"), special("s"), sequence(...), choice(...), optional(x), zeroOrMore(x), oneOrMore(x), /* */ comments

A repeated rule name is a warning, and both rules are drawn. A syntax error skips to the end of its rule; the other rules are still drawn.

Not drawn

The title is read but not drawn. Repeat bounds other than optional, zero or more, and one or more are drawn as a plain loop. Mermaid’s railroad config and its themes are not used.

Swimlane diagrams

sirene draws Mermaid’s swimlane diagrams (swimlane-beta) as images and as text: a flowchart whose top-level subgraphs are lanes, side by side across the flow.

swimlane-beta LR
  subgraph buyer [Buyer]
    choose([Choose product])
    pay[Pay invoice]
  end

  subgraph store [Store]
    reserve[Reserve stock]
    ship((Ship))
  end

  choose --> reserve
  reserve -.->|Invoice ready| pay
  pay ==> ship
  ship --> audit[Audit]
the drawing of the mermaid source above

Everything else is flowchart syntax: see Syntax. See crates/sirene-core/tests/fixtures/swimlane/ for more. In the editor a swimlane diagram is read-only on the drawing side.

Lanes

  • The header direction (TB when there is none) is the flow; lanes run along it, in the order they are declared.
  • Nodes outside every lane share an untitled last lane.
  • A node listed in two lanes stays in the first, with a warning; the second lane is dropped if that leaves it empty and no edge names it.
  • A subgraph inside a lane is drawn as a plain box, with a warning.

Not drawn

An edge to or from a lane itself. Mermaid’s lane colors and its redux-color theme and neo look are not used. Ranks follow every edge, so a diagram can be longer along the flow than Mermaid’s, which ranks each lane apart from the edges between lanes.

Cynefin diagrams

sirene draws Mermaid’s Cynefin diagrams (cynefin-beta) as images and as text: items placed in the five domains of the Cynefin framework, with transitions between domains.

cynefin-beta
  title Strategy Categorization

  complex
    "Market research"

  complicated
    "Competitive analysis"

  clear
    "Standard pricing"

  chaotic
    "Crisis management"

  complex --> complicated : "Pattern identified"
  complicated --> clear : "Best practice codified"
  clear --> chaotic : "Complacency"
  chaotic --> complex : "Stabilized"
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/cynefin/ for more. In the editor a Cynefin diagram is read-only on the drawing side.

Syntax

  • cynefin-beta (or cynefin-beta:) first, then title, accTitle, and accDescr as usual.
  • A domain keyword (complex, complicated, clear, chaotic, or confusion) opens a domain; the quoted items ("..." or '...') after it, on its line or the lines below, belong to it. A domain declared again replaces its items, with a warning.
  • from --> to adds a transition, with an optional : "label". A transition from a domain to itself is dropped, with a warning.
  • showDomainDescriptions: false under config: cynefin: in the frontmatter hides each domain’s decision model and practice.

Domains are always placed the same way: Complex top left, Complicated top right, Chaotic bottom left, Clear bottom right, and Confusion in the middle. Confusion shows three items and a +N more badge for the rest. The area grows to fit long or many items.

Not drawn

Mermaid’s width, height, padding, boundaryAmplitude, and seed options and its cynefin theme variables. Boundaries wave the same way in every diagram.

Event modeling diagrams

sirene draws Mermaid’s event modeling diagrams (eventmodeling) as images and as text: UI, processor, command, read model, and event frames along a timeline, in swimlanes, with relations between them.

eventmodeling
  tf 01 ui CartUI
  tf 02 cmd AddItem { description: string }
  tf 03 evt ItemAdded
the drawing of the mermaid source above

See crates/sirene-core/tests/fixtures/eventmodel/ for more. In the editor an event modeling diagram is read-only on the drawing side.

Syntax

  • eventmodeling first, then title, accTitle, and accDescr as usual. Comments are %%, //, or /* ... */.
  • tf NN type Name (or timeframe) adds a time frame. NN is a frame number of one to three digits, unique in the diagram. type is ui, pcr (processor), cmd (command), rmo (readmodel), or evt (event).
  • rf NN type Name (or resetframe) adds a reset frame, which takes no inferred relation.
  • After the name: ->> NN relations from other frames, any number; [[Data]] to show a data block; inline data in { ... }, "...", or '...', optionally after a type such as `json`.
  • data Name { ... } defines a data block over the lines below {, up to a } line.
  • entity, note NN { ... }, and gwt NN given ... when ... then ... are read but not drawn.

A frame with no ->> takes a relation from the latest earlier frame in another lane. A ->> source of the wrong type (a command’s must be a UI or processor, an event’s a command, a read model’s an event, and a UI’s or processor’s a read model) is an error, as are repeated frame numbers and undefined frames or data blocks.

Lanes

UIs and processors go in UI/Automation, commands and read models in Command/Read Model, and events in Events. A name with a namespace, such as Cart.ItemAdded, goes in its own lane in that group (Stream: Cart), after the group’s lane.

In text, a relation that cannot be drawn as a straight vertical arrow is listed below the lanes as 01 From → 02 To (-> in ASCII).

Not drawn

Notes, gwt scenarios, entity declarations, data types, and the em* theme variables.

Agentflow diagrams

sirene draws Mermaid’s agentflow diagrams (agentflow-beta) as images and as text: a flowchart of flow containers with agentflow’s shapes and edges.

agentflow-beta LR
  global
    user["User"]
  end

  flow plan["Planner"]
    goal@{ shape: input, label: "Read the goal" }
    split{"Split into tasks?"}
  end

  flow work["Workers"]
    search@{ shape: tool, label: "Web search" }
    notes@{ shape: refdoc, label: "Notes" }
    act@{ shape: action, label: "Draft answer" }
  end

  connector bus["Message bus"]

  user --> goal
  goal --> split
  split -- yes --> search
  split -->|no| act
  search --> notes
  notes -.- bus
  bus --> act
  act --x user
the drawing of the mermaid source above

Everything else is flowchart syntax: see Syntax. See crates/sirene-core/tests/fixtures/agentflow/ for more. In the editor an agentflow diagram is read-only on the drawing side.

Containers

  • flow id["Title"] ... end groups nodes; flow id and a bare flow are untitled. Flows nest, and flow id["Title"]@{ view: collapsed } draws one as a single node.
  • global ... end holds nodes that belong to no flow.
  • connector id["Title"] declares a rounded node; without a title its label is its id.
  • subgraph is an error.

Shapes and edges

  • A node is a rounded rectangle unless its brackets or @{ shape } say otherwise. {}, {{}}, [[]], and [/ /] keep their flowchart shapes.
  • @{ shape } takes task, tool, input, decision, refdoc, and action, and their flowchart names. A shape agentflow removed (e.g. cylinder) is an error and another Mermaid shape (e.g. cloud) a warning; both draw rounded.
  • Edges are -->, --x, and -.-, with -- text --> or |text| labels. Any other edge is an error.

Not drawn

Mermaid’s agentflow theme colors and neo look.

Graphviz DOT

sirene draws Graphviz DOT graphs as images and as text, with its own layered layout:

digraph classes {
  node [shape=record]
  Animal [label="{Animal|+ name : string\l+ age : int\l|+ die() : void\l}"]
  Dog [label="{Dog|+ bark() : void\l}"]
  Cat [shape=Mrecord, label="{Cat|+ meow() : void}"]
  Dog -> Animal [arrowhead=empty]
  Cat -> Animal [arrowhead=empty]
}
the drawing of the dot source above

A .dot or .gv file, a dot or graphviz block in Markdown, and any source given with --lang dot is DOT; so is stdin or another file that starts with graph, digraph, or strict and then { (after an optional ID). --lang mermaid reads a source as Mermaid instead. Directories are scanned for .dot and .gv files. In the editor a DOT graph is read-only on the drawing side. Only the first graph in a file is drawn.

What is read

SyntaxDrawn as
digraph, graph, strictarrows at heads, no arrows, repeated edges merged
a -> b -> c, a -> {b c}edge chains, and edges to every node in a subgraph
node [...], edge [...]defaults for later statements in the same braces
subgraph cluster_x { ... }a cluster titled by its label, filled by bgcolor; other subgraphs only scope defaults
rankdir, label, bgcolorthe direction, the title, and the background
shapethe nearest sirene shape; record and Mrecord as compartments
stylefilled, rounded (nodes only; clusters stay square, with a warning), dashed, dotted, bold, invis
color, fillcolor, fontcolor, penwidthborder, fill, text color, line width
label, headlabel, taillabellabels, with \n, \l, \N, \G, \E, \T, \H
arrowhead, arrowtail, dir, minlenend markers, which ends have them, and rank span
rank=same, min, max, source, sinknodes sharing a rank, or in the first or last
constraint=false, group, orderingedges that do not rank, straight edges in a group, source order
compound=true with lhead, ltailedges ending at a cluster’s border
a:e, a:p, tailport, headportcompass ports; record ports with rankdir=LR or RL
HTML <TABLE> node labelscompartments, with <HR/> sections and PORT cells

Colors are X11 names, #rrggbb, #rrggbbaa, or H,S,V fractions. See spec/graphviz-dot.md for the full list of shapes and arrows.

Errors

Syntax errors, -> in a graph, -- in a digraph, and subgraphs nested more than 64 deep are errors. An attribute that is not drawn, an unknown shape, color, arrow, or style, and a second graph in a file are warnings, each once.

Not drawn

The layout is sirene’s, not Graphviz’s. Record ports in top-down graphs (the edge joins the node), images, node sizes, fonts, and other engines’ layout attributes (pos, overlap, splines) are warned about and ignored. HTML labels other than node tables are drawn as their text.

PlantUML

sirene draws PlantUML diagrams as images and as text, with its own layouts:

@startuml
actor User
participant Server
User -> Server : log in
Server --> User : token
@enduml
the drawing of the plantuml source above

A .puml, .plantuml, .pu, or .iuml file, a plantuml or puml block in Markdown, and any source given with --lang plantuml is PlantUML; so is stdin or another file with an @start line (text before it is ignored). Directories are scanned for those extensions. Inside @startuml, the kind is picked from the statements, as PlantUML does. In the editor a PlantUML diagram is read-only on the drawing side. Only the first @start … @end block in a file is drawn.

Kinds

KindStart
Sequence@startuml with participants and messages, and anything no other row matches
Activity, with swimlanes@startuml with start, :action;, if, while, fork, |Lane|
Class and object@startuml with class, interface, enum, object, map
State@startuml with state, [*]
Use case, component, and deployment@startuml with usecase, (Name), component, [Name], node, cloud, …
Timing@startuml with robust, concise, clock, binary, analog
Networknwdiag { ... } in @startuml or @startnwdiag
Mindmap and WBS@startmindmap, @startwbs
Gantt@startgantt, or @startuml with [Task] lasts ... or Project starts ...
JSON and YAML@startjson, @startyaml
DOT@startdot
EBNF and regular expressions@startebnf, @startregex
Chen entity-relationship@startchen
Chronology@startchronology
File trees@startfiles

actor and database alone do not pick a kind: a diagram of actors and arrows is a sequence diagram until a use case or component appears. The examples include a sequence, class, activity, and timing diagram. See spec/plantuml.md and the spec/plantuml-*.md pages for what each kind reads.

Errors

Syntax a kind does not read is an error on its line; a construct that is read but not drawn (a participant’s stereotype, an unknown attribute, manual time-axis) is a warning. !include, !includeurl, !includesub, !include_many, !include_once, and !import are errors, since sirene reads no other files; other ! lines (!define, !theme, …) are warnings and skipped. skinparam lines are warnings, except skinparam actorStyle in use case diagrams. A second @start block in a file is a warning. A #color before a sequence frame or else label (alt#Gold text) is a warning and left out of the label. In sequence diagrams autoactivate on activates the target of each message until autoactivate off.

Not drawn

Salt (@startsalt), ditaa, math, LaTeX, wire, board, creole, and def diagrams, and any other @start word, are errors naming the kind. So is the older activity syntax ((*) --> "First"); use start and :action;. The preprocessor (!define, !function, variables, conditionals) is not evaluated: the lines in every !if branch are read as statements, and macro calls are read as written, so they are usually errors on their own lines. The layouts are sirene’s, not PlantUML’s.

Development

The workspace has four crates:

CrateWhat
sirene-corethe parser, model, edits, layout, and SVG, PNG, and ASCII renderers; no GUI
sirene-guithe editor, on gpui and GPUI Kit
sirenethe binary; the gui feature (on by default) links sirene-gui
xtaskpackaging and release-signing tasks; not published

The behavior of each part is specified in spec/, with stable ids (FLOWCH-7, GUISHE-5) that tests and code comments refer to. spec/README.md has the feature status table.

Building

cargo build                                  # with the editor
cargo build -p sirene --no-default-features  # the command line only
cargo run -p sirene -- examples/shapes.mmd

On Linux the editor needs the XCB, xkbcommon, Wayland, fontconfig, and Vulkan development packages (see Install).

Checks

bash scripts/ci.sh

runs cargo fmt --check, clippy with warnings as errors, the tests, and the line coverage gate (needs cargo install cargo-llvm-cov). CI runs the same script.

This site

The guide is an mdBook in docs/, and the landing page is docs/landing/. To preview:

cargo build -p sirene --no-default-features
mdbook serve docs

The docs/samples.py preprocessor (Python 3) draws each mermaid, plantuml, or dot code block with that build and adds the drawing and sirene ascii text below it. A block sirene reports an error for fails the build; ```mermaid no-render leaves a block as source only. Untagged blocks are not drawn.

The pages redraw a sample as it is edited, and the playground draws as you type, with sirene-wasm (wasm/), sirene-core built for WebAssembly. Without the module they show that it is not built. To build it into the preview:

cargo build --profile wasm -p sirene-wasm --target wasm32-unknown-unknown
mkdir -p docs/src/wasm
cp target/wasm32-unknown-unknown/wasm/sirene_wasm.wasm docs/src/wasm/sirene.wasm

.github/workflows/pages.yml builds both on pull requests and publishes them on each push to main that changes docs/, examples/, crates/, or wasm/.

Packaging

cargo build --release --package sirene
cargo xtask bundle --binary target/release/sirene    # target/bundle/Sirene.app
cargo xtask icon                                     # target/bundle/sirene.{icns,png}
cargo xtask cask --url URL --sha256 HEX --homepage URL

Releasing

Signing setup

Before releasing, configure the repository’s signing environment to allow deployments only from main. Its ZIPSIGN_KEY secret must contain the base64-encoded 64-byte signing key pair matching crates/sirene/release.pub. The signing task refuses a mismatched key.

cargo xtask gen-key --out DIR writes a new release.key and release.pub. Keep the private release.key outside the repository and never commit it. The checked-in verifying key is crates/sirene/release.pub. For an existing release key, retain that pair; replacing it needs the key rotation steps, so older installations can still update.

Release steps

main carries the next -dev version between releases. CI’s semver job compares sirene-core’s API with its latest crates.io release; a change that breaks it also bumps the -dev version to the next minor (0.5.1-dev to 0.6.0-dev), so the release is numbered for it.

To release X.Y.Z:

  1. Set version in the root Cargo.toml, and the matching [workspace.dependencies] pins, to X.Y.Z.
  2. Add a ## [X.Y.Z] section to CHANGELOG.md.
  3. Merge to main.

.github/workflows/release.yml then runs CI and the RustSec audit, builds the binaries and Sirene.app. The sign job builds xtask before exposing the secret, decodes the key with umask 077, and signs the tarballs before their attestations and SHA256SUMS are generated. The wasm job builds sirene-wasm-X.Y.Z.tar.gz (Web pages) and attests it, and packs the @jaemk/sirene npm package. The release job creates the vX.Y.Z release with the signed tarballs, app, sirene-wasm tarball, and checksums. After approval in the release environment, publish publishes sirene-core, sirene-gui, and sirene to crates.io, commits the Homebrew formula, the cask, and the next -dev version to main, then publishes @jaemk/sirene to npm.

npm setup

npm publishing is trusted publishing only. On npmjs.com, @jaemk/sirene’s settings name the trusted publisher (GitHub Actions, jaemk/sirene, workflow release.yml, environment release) and set publishing access to require two-factor authentication and disallow tokens.

To retry a failed release, dispatch the release workflow from main. If the release already exists, main must still be at the commit named by its vX.Y.Z tag; the workflow refuses to rebuild that version from a different commit. Dispatches from other branches skip the release.

See spec/workspace.md (WORKSP-8, WORKSP-9) and spec/macos-packaging.md for the details.