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 FILEopens 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, andsirene asciirender a diagram file, a Markdown file’s diagram blocks, or stdin without opening a window, and can watch files for changes.svgandpngalso 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:
- Flowcharts (
flowchartandgraph), swimlane diagrams (swimlane-beta), and agentflow diagrams (agentflow-beta) - Sequence diagrams (
sequenceDiagram) and ZenUML diagrams (zenuml) - State diagrams (
stateDiagram-v2), class diagrams (classDiagram), ER diagrams (erDiagram), requirement diagrams (requirementDiagram), and use case diagrams (usecase-beta) - Block diagrams (
block-beta), architecture diagrams (architecture-beta), and C4 diagrams (C4Contextand the other C4 types) - Git graphs (
gitGraph), timelines (timeline), gantt charts (gantt), and event modeling diagrams (eventmodeling) - Pie charts (
pie), XY charts (xychart-beta), quadrant charts (quadrantChart), radar charts (radar-beta), sankey diagrams (sankey-beta), treemaps (treemap-beta), and venn diagrams (venn-beta) - Mindmaps (
mindmap), tree views (treeView-beta), ishikawa diagrams (ishikawa-beta), kanban boards (kanban), user journeys (journey), Wardley maps (wardley-beta), and Cynefin diagrams (cynefin-beta) - Packet diagrams (
packet), railroad diagrams (railroad-ebnf-betaand the other notations), and info diagrams (info)
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:
| Variable | Default | Meaning |
|---|---|---|
SIRENE_VERSION | the latest release | the version to install, e.g. 0.2.0 |
SIRENE_INSTALL_DIR | ~/.local/bin | where to put sirene |
SIRENE_TARGET | this platform’s, musl on Linux | the 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
┌──────┐
┌►│ Done │
╱─────╲ ┌─yes─┘ └──────┘
┌───────┐ │ ├─┘
│ Start ├───►│ Ok? ├───no──┐ ┌───────┐
└───────┘ │ │◄┐ └►│ Retry │
╲─────╱ └───────┤ │
└───────┘
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
┌───────┐ ┌─────┐
│ Alice │ │ Bob │
└───┬───┘ └──┬──┘
│ │
│ hello │
├─────────►│
│ │
│ hi │
│◄┄┄┄┄┄┄┄┄┄┤
│ │
┌───┴───┐ ┌──┴──┐
│ Alice │ │ Bob │
└───────┘ └─────┘
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.
| Option | Meaning |
|---|---|
-o, --output PATH | where to write (- is stdout for a single diagram); default FILE with .png, or stdout when reading stdin |
--theme light|dark | the colors (default light) |
--quality draft|normal|fine | the detail (default fine); large drawings are shrunk to fit |
--scale N | pixels 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
 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]
```

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 --> Cthat loses its middle is split, andclass,style,click, andlinkStylestatements 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’sdirectionline. - 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 --> Bmoves 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
linkStylenumbers 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, ordot). - 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 namesirene png notes.mdgives block N.
Export
- File > Export as PNG (secondary-shift-e) and Export as SVG write the drawing in the window’s
colors, as
sirene pngandsirene svgwould. - 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
| Keys | Action |
|---|---|
| secondary-n | New document |
| secondary-o | Open |
| secondary-s | Save |
| secondary-shift-s | Save As |
| secondary-r | Reload from disk |
| secondary-shift-e | Export as PNG |
| secondary-shift-c | Copy the drawing as an image |
| secondary-w | Close the window |
| secondary-q | Quit |
| secondary-e | Show or hide the source pane |
| secondary-i | Show or hide the styles panel |
| secondary-shift-] | Next diagram block of a Markdown file |
| secondary-shift-[ | Previous diagram block of a Markdown file |
Editing
| Keys | Action |
|---|---|
| secondary-shift-n | Add 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-z | Undo |
| secondary-shift-z | Redo |
| secondary-a | Select 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
| Keys | Action |
|---|---|
| secondary-= or secondary-+ | Zoom in |
| secondary– | Zoom out |
| secondary-0 | Actual size |
| secondary-9 | Fit the window |
| secondary-8 | Fit the selection |
| arrows (drawing) | Pan; shift for further |
| secondary-scroll | Zoom |
Mouse
| Gesture | Action |
|---|---|
| click | Select a node or edge, or clear the selection on empty space |
| shift-click | Add to or remove from the selection |
| double-click | Edit a label; on empty space, add a node |
| right-click | The menu for the item under the pointer or the selection |
| drag from a node to a node | Connect them |
| drag from a node to empty space | Add a node linked from it |
| drag a node onto a subgraph | Move it into the subgraph |
| drag empty space, or scroll | Pan |
Settings
The editor keeps its settings in a settings file of key = value lines:
| Platform | Path |
|---|---|
| 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.
| Key | Values | Set by |
|---|---|---|
appearance | system, light, dark | View > Appearance |
window | WxH, e.g. 1200x760 | the size of the last window closed |
source | shown, hidden | showing or hiding the source pane |
source_width | pixels | dragging the divider |
recent | a path, up to 10 lines, most recent first | opening 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 aSeverity(an error is what Mermaid would refuse to draw). The diagram is still drawn.diagnostic::LineIndexfinds the lines and columns of many diagnostics in one pass. - A diagram’s own
themeandthemeVariablesapply over the theme passed in. Lowered::scenegives the display list for other renderers, with text measured by anyscene::TextMetrics.scene::png(featurepng) draws text with embedded Noto Sans faces, so images are the same on every machine.flowchart::parseandflowchart::editgive 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-corebuilds forwasm32-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.wasm | the module (about 2.7 MB, 0.9 MB gzipped); SVG and ASCII output |
sirene-wasm.js | the loader: a plain script that sets window.SireneWasm |
LICENSE-MIT, LICENSE-APACHE, THIRD-PARTY-NOTICES | licenses |
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 --> 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}`);
}
| Option | Values |
|---|---|
format | svg (default), ascii |
lang | detect (default, from the source’s header), mermaid, plantuml or puml, dot or graphviz |
theme | dark (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 . Named codes are the HTML 4 set (#copy;,♥,→,—, …)."`...`"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.:::nameadds a class.endis 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
| Stroke | Forms |
|---|---|
| normal | ---, --> |
| thick | ===, ==> |
| dotted | -.-, -.-> |
| invisible | ~~~ |
>,x, andoare 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 & Dadds 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, fore1@{ ... },class, andstyle.
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 }
╭──────────╮ ┌─────────┐ ╱──────────╲ ├──────────┤ │ Process ├───►│ Decision ├───►│ Database │ └─────────┘ ╲──────────╱ ╰──────────╯ ┌────────┐ │ Report │ └────────┘ ╭───────╮ ├───────┤ │ Queue │ ╰───────╯
When a node has both, @{ shape } wins, and the bracket text stays its label.
| Name | Delimiters | Aliases |
|---|---|---|
rect | A[text] | proc, process, rectangle |
rounded | A(text) | event |
stadium | A([text]) | terminal, pill |
fr-rect | A[[text]] | subprocess, subproc, framed-rectangle, subroutine |
cyl | A[(text)] | db, database, cylinder |
circle | A((text)) | circ |
dbl-circ | A(((text))) | double-circle |
| (ellipse) | A(-text-) | |
odd | A>text] | |
diam | A{text} | decision, diamond, question |
hex | A{{text}} | hexagon, prepare |
lean-r | A[/text/] | lean-right, in-out |
lean-l | A[\text\] | lean-left, out-in |
trap-b | A[/text\] | priority, trapezoid-bottom, trapezoid |
trap-t | A[\text/] | manual, trapezoid-top, inv-trapezoid |
datastore | data-store | |
folder | directory | |
bucket | ||
console | ||
browser | ||
person | ||
bang | ||
cloud | ||
text | ||
notch-rect | card, notched-rectangle | |
lin-rect | lined-rectangle, lined-process, lin-proc, shaded-process | |
sm-circ | start, small-circle | |
fr-circ | stop, framed-circle | |
fork | join | |
hourglass | collate | |
brace | comment, brace-l | |
brace-r | ||
braces | ||
bolt | com-link, lightning-bolt | |
doc | document | |
delay | half-rounded-rectangle | |
h-cyl | das, horizontal-cylinder | |
lin-cyl | disk, lined-cylinder | |
curv-trap | curved-trapezoid, display | |
div-rect | div-proc, divided-rectangle, divided-process | |
tri | extract, triangle | |
win-pane | internal-storage, window-pane | |
f-circ | junction, filled-circle | |
notch-pent | loop-limit, notched-pentagon | |
flip-tri | manual-file, flipped-triangle | |
sl-rect | manual-input, sloped-rectangle | |
docs | documents, st-doc, stacked-document | |
st-rect | procs, processes, stacked-rectangle | |
bow-rect | stored-data, bow-tie-rectangle | |
cross-circ | summary, crossed-circle | |
tag-doc | tagged-document | |
tag-rect | tagged-rectangle, tag-proc, tagged-process | |
flag | paper-tape | |
lin-doc | lined-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]
┌───────┐ ╱────────╲ ┌──────┐ │ Start ├───►│ Ready? ├──yes─►│ Ship │ └───────┘ ╲────────╱ └──────┘
The same in frontmatter, with themeVariables:
---
config:
theme: base
themeVariables:
primaryColor: '#BB2528'
lineColor: '#F8B229'
fontSize: 18px
---
flowchart LR
A --> B
┌───┐ ┌───┐ │ A ├───►│ B │ └───┘ └───┘
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
┌─ Application ─────────────────────────────────────────────────────────────────┐ ┌─ Data ─────────────┐
│ ┌────────────────────────────────────┼─┐ │ ╭──────────╮ │
│ ┌──────────────┐ │ │ └───────────┼───►├──────────┤ │
│ │ ├─┘ ┌───────────┐ ┌┬────────┬┐ │ ┌────┼───►│ Postgres │ │
│ ┌►│ API server 1 ├──────►> Job queue │ ││ Worker │├──┼─────┐ │┌───┼───►│ │ │
│ ┌──┘ │ ├┄┄┐ ┌►> ├───►││ │├──┼────┐│ ││ │ ╰──────────╯ │
│ ╱───────────────╲ │ └──────────────┘ ┆ │ └───────────┘ └┴────────┴┘ │ ┌──┼┼──┘│ │ │
╭──────╮ ┌─────┐ │ < Load balancer ├─┘ ┌┼──┘ │ │┌┄┼┼┄┄┄┼┄┐ │ ╭───────╮ │
( User ├───►│ CDN ├────┼─►< ├─┐ ┌──────────────┐ │└┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┼┘┌┼┼┄┄┄┼┐└┄┼┄┄┄┄►├───────┤ │
╰──────╯ └─────┘ │ ╲───────────────╱ └──┐ │ ├─┘ │ │ ┆│└───┘└┄┄┼┄┄┄┄►│ Redis │ │
│ └►│ API server 2 ├──────────────────────────────────────┼─┘ ┆└───┐ │ ╰───────╯ │
│ │ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┘ │ │ │
│ └──────────────┘ │ │ │ ╭──────────────╮ │
└───────────────────────────────────────────────────────────────────────────────┘ │ │ ├──────────────┤ │
└────┼─►│ Object store │ │
│ ╰──────────────╯ │
└────────────────────┘
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];
}
┌─ outputs ───┐
│ ╭─────╮ │
┌─┼──►│ svg │ │
┌─ sources ────────────────────────────────┐ │ │ ╰─────╯ │
│ ╭────────╮ │ ┌──┘ │ │
┌───────╮ │ ╭────────╮ ╭────────╮ │ ├──┼─┘ │ ╭─────╮ │
│ tests ├┄┄┄┄┼┄►│ parser ├───►│ layout ├───►│ render ├──┼──────┼──►│ png │ │
└───────┘ │ ╰────────╯ ╰────────╯ │ ├──┼─┐ │ ╰─────╯ │
│ ╰────────╯ │ │ │ │
└──────────────────────────────────────────┘ └──┐ │ ╭───────╮ │
└─┼─►│ ASCII │ │
│ ╰───────╯ │
└─────────────┘
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
Checkout
o
/|\ ┌───────────┐ ┌───────────┐ ┌─────────┐
/ \ │ Web Shop │ │ Payments │ │ Orders │
Customer └─────┬─────┘ └─────┬─────┘ └────┬────┘
│ │ │ │
│ place order │ │ │
├────────────────────►┃ │ │
│ ┃ │ │
│ ┃ charge card │ │
│ ├──────────────►│ │
│ ┃ │ │
┌─alt [approved]────────┼───────────────┼──────────────┼─┐
│ │ ┃ receipt │ │ │
│ │ ┃◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │
│ │ ┃ │ │ │
│ │ ┃ save order │ │
│ │ ├───────────────┼─────────────►│ │
│ │ ┃ │ │ │
│ │ confirmation ┃ │ │ │
│ │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │ │
│ │ ┃ │ │ │
├┄[declined]┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┤
│ │ ┃ declined │ │ │
│ │ ┃◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │
│ │ ┃ │ │ │
│ │ask for another card ┃ │ │ │
│ │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ │ │
│ │ ┃ │ │ │
└─┼─────────────────────┼───────────────┼──────────────┼─┘
o ┌─────┴─────┐ ┌─────┴─────┐ ┌────┴────┐
/|\ │ Web Shop │ │ Payments │ │ Orders │
/ \ └───────────┘ └───────────┘ └─────────┘
Customer
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
CI pipeline
┌─ Release, on main ─────────────────────────────────────────────┐
│ ╭───────────╮ │
│ ┌────────────────┐ ├───────────┤ │
│ ┌►│ Build binaries ├───►│ crates.io │ │
│ ╱──────────────╲ ┌─yes─┘ └────────────────┘ ╰───────────╯ │
┌────────────────┐ │ │ New version? ├─┘ │
╱────────────────────────╲ ┌─yes──►│ Ready to merge ├━━━━┼━►│ ├─┐ ╭───────────────╮ │
┌───────┐ │ Coverage at least 98%? ├─┘ └────────────────┘ │ ╲──────────────╱ └─no───►│ Nothing to do │ │
┌────────────────┐ ┌►│ Tests ├───────────►│ ├─┐ │ ╰───────────────╯ │
╭──────────────────╮ │ fmt and clippy ├────┘ └───────┘ ╲────────────────────────╱ └─no──┐ ┌┬──────────────┬┐ └────────────────────────────────────────────────────────────────┘
( Push to a branch ├────────►│ ├┄┐ └►││ Fail the run ││
╰──────────────────╯ └────────────────┘ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄warnings┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄►││ ││
└┴──────────────┴┘
┌─ Checks run on each push ─┐
│ │
│ ┌───────────┐ │
│ │ cargo fmt │ │
│ └─────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ cargo clippy │ │
│ └───────┬──────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ cargo test │ │
│ └────────────┘ │
│ │
└───────────────────────────┘
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
Fulfillment
●
│
▼
╭───────────────╮
│ Receive order │
╰───────┬───────╯
│
▼
╱───────────╲
│ In stock? │
╲──┬─────┬──╱
│ │
┌───┘ └───┐
│ │
yes no
│ │
┌──┘ └───┐
▼ ▼
╭────────────╮ ╭─────────────────────╮
│ Pick items │ │ Order from supplier │
╰──────┬─────╯ ╰──────────┬──────────╯
│ │
└───┐ ┌────┘
│ │
│ │
└────┐ ┌────┘
▼ ▼
━┬━┬━
│ │
┌───┘ └───┐
│ │
│ │
┌──┘ └───┐
▼ ▼
╭─────────────╮ ╭──────────╮
│ Charge card │ │ Pack box │
╰──────┬──────╯ ╰─────┬────╯
│ │
└──┐ ┌───┘
│ │
│ │
└───┐ ┌───┘
▼ ▼
━━┬━━
│
▼
╱─────────────╲
│ More boxes? │
╲──┬───────┬──╱
│ ▲ │
┌┘ │ └───┐
│ │ │
yes │ no
│ │ │
┌┘ │ └──┐
▼ │ ▼
╭────────┴──╮ ╭──────╮ ┌─────────╮
│ Label box │ │ Ship │┄┄│ tracked │
╰───────────╯ ╰───┬──╯ └─────────┘
│
▼
◉
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
╭──────────────╮
( Open the app )
╰───────┬──────╯
│
▼
╱────────────╲
│ Signed in? │
╲───┬─────┬──╱
│ │
│ └──────┐
│ │
│ no
│ │
│ └──────┐
│ ▼
│ ┌────────────────────┐
│ ╱ Email and password ╱
│ └─────┬──────────────┘
│ │ ▲
│ ▼ │
│ ╱────────╲ │
│ │ Valid? │ │
│ ╲──┬───┬─╱ │
│ │ │ │
│ ┌┘ └───┐ └┐
│ │ │ │
│ no yes │
│ │ │ │
└┐ ┌┘ ┌─┼────┘
│ │ │ └──────────────┐
│ ▼ │ ▼
│ ┌────────────┴───┐ ╱────────────────╲
yes │ Show the error │ │ Two-factor on? │
│ └────────────────┘ ╲────┬───────┬───╱
│ │ │
└──────────────┐ ┌───────────┘ ┌──┘
│ │ │
│ │ yes
│ │ │
│ │ ┌───┘
│ │ ▼
│ │ ┌────────────────┐
│ │ ╱ Enter the code ╱
│ │ └────┬───────────┘
│ │ │ ▲
│ └┐ │ │
│ │ │ │
│ no │ no
│ │ │ │
│ ┌┘ │ │
│ │ ▼ │
│ │ ╱───────────┴───╲
│ │ │ Code matches? │
│ │ ╲───┬───────┬───╱
│ │ │ │
│ │ ┌─┘ └─┐
│ │ │ │
│ │ yes no, 3 tries
│ │ │ │
│ │ ┌──┘ └─┐
▼ ▼ ▼ ▼
┌─────────────┐ ┌──────────────────┐
│ Home screen │ │ Lock the account │
└─────────────┘ └──────────────────┘
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
┌─────────┐
│ Shipped ├━━━━┓ ╭───────────╮
┌────────┐ ┌►│ ├─┐ ┗━━━━►( Delivered ) ┌────────┐
┌►│ Packed ├───────────┘ └─────────┘ │ ┌───►( ├────────o│ Review │
┌──────┐ ┌──┘ └────────┘ └──┐│ ╰───────────╯ └────────┘
│ Paid ├─┘ ┌────────────────┼┘
┏►│ │◄─────────────────exchange─┘ │ ┌─────────────────┐
┏━paid━┛ └──────┘ └─x│ Lost in transit │ ┌───────────┐
┌────────┐ ┃ └─────────────────┘ │ Cancelled │
┌──────┐ │ Placed ├━┛ ┌►│ │
│ Cart ├───►│ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄timeout┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘ └───────────┘
└──────┘ └────────┘
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
Request timing
════════waiting════════
Clock ───┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌─┐ ┌──┐ ┌─┐ ┌──┐ ┌─┐
└─┘ └──┘ └─┘ └──┘ └─┘ └──┘ └──┘ └──┘ └──┘ └──┘ └───
Enable ┌───────────────────────────────────────────┐
───────────┘ └─────
Web Browser Processing ┌─────────────────────┐
Waiting │ └─────────────────────┐
Idle ───────────┘ └─────
▲─URL── 200 ms ───────►
┆
Web User ┌──────────┬───────────────────────────────────────────┬────┐
│ Idle │ Waiting │Idle│
└──────────┴───────────────────────────────────────────┴────┘
┬──────────┬──────────┬──────────┬──────────┬──────────┬─────
0 100 200 300 400 500
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
┌───────────┐ ╭──────────╮ ╱─────────╲ ┌───────────┐
│ Rectangle │ ├──────────┤ │ Diamond │ ╱ Trapezoid ╲
└─────┬─────┘ │ Cylinder │ ╲────┬────╱ └─────┬─────┘
│ ╰─────┬────╯ │ │
│ │ │ │
▼ ▼ ▼ ▼
╭─────────╮ ╭────────╮ ╱─────────╲ ┌────────────────────┐
│ Rounded │ ( Circle ) < Hexagon > ╲ Inverted trapezoid ╱
╰────┬────╯ ╰────┬───╯ ╲────┬────╱ └──────────┬─────────┘
│ │ │ │
▼ ▼ ▼ ▼
╭─────────╮ ╔═══════════════╗ ┌────────────┐ ╭─────────╮
( Stadium ) ║ Double circle ║ ╱ Lean right ╱ ( Ellipse )
╰────┬────╯ ╚═══════┬═══════╝ └──────┬─────┘ ╰────┬────╯
│ │ │ │
▼ ▼ ▼ ▼
┌┬────────────┬┐ ┌────────────┐ ┌───────────┐ ┌──────┐
││ Subroutine ││ > Asymmetric │ ╲ Lean left ╲ │ bare │
└┴────────────┴┘ └────────────┘ └───────────┘ └──────┘
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
Shop model
┌──────────────────┐
│ Order │
├──────────────────┤
│ +status : Status │
├──────────────────┤
│ +total() : Money │
└─────────────┬────┘
◆1 │
┌────────┘ │
│ │
contains > │
│ │
┌────┘ └──┐
│ │
┌───────────┼─── catalog ─┐ │
│ │many │ │
│ ┌─────────┴────────┐ │ │
│ │ «abstract» │ │ │
│ │ Product │ │ │
│ ├──────────────────┤ │ │
│ │ -id : UUID │ │ │
│ ├──────────────────┤ │ ▼
│ │ +price() : Money │ │ ┌───────────────┐
│ └──────────────────┘ │ │ «enumeration» │
│ △ │ │ Status │
│ │ │ ├───────────────┤
│ ┌────────┴───────┐ │ │ NEW │
│ │ Book │ │ │ PAID │
│ ├────────────────┤ │ │ SHIPPED │
│ │ +isbn : String │ │ ├───────────────┤
│ ├────────────────┤ │ └───────────────┘
│ └────────┬───────┘ │
│ ┆ │
│ ▽ │
│ ┌─────────────┐ │
│ │ «interface» │ │
│ │ Shippable │ │
│ └─────────────┘ │
│ │
└─────────────────────────┘
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
┌────────┐ ┌────────────────┐
┌►│ Dashed ├───►│ Markdown label │
┌──────┐ ┌──┘ └────────┘ └────────────────┘
┌─────────┐ ┌─────┐ │ Cold ├─┘
│ Default ├───►│ Hot ├───►│ ├─┐ ┌────────┐
└─────────┘ └─────┘ └──────┘ └──┐ │ Line 1 │
└►│ Line 2 │
└────────┘
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!
┌───────┐ ┌───────┐
│ Alice │ │ John │
└───┬───┘ └───┬───┘
│ │
│Hello John, how are you? │
├────────────────────────►│
│ │
│ Great! │
│◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ │
│ See you later! │
├────────────────────────>│
│ │
┌───┴───┐ ┌───┴───┐
│ Alice │ │ John │
└───────┘ └───────┘
In the editor a sequence diagram is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
participant A, participant A as Alice, actor A | a 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: text | a 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: text | a loop back to the same lifeline |
A->>+B, B-->>-A, activate A, deactivate A | activation bars, offset when nested (heavy lifelines in text) |
note left of A, note right of A, note over A,B | a note beside or across lifelines |
loop, alt/else, opt, par/and, critical/option, break | a frame with its kind and label, and dashed dividers; frames nest |
rect COLOR ... end | a colored background (a dotted frame in text) |
box COLOR Title ... end | a group around the participants declared inside; it holds only declarations |
create participant B, destroy B | a header where the participant is created, and a cross where its lifeline ends |
autonumber, autonumber 10 5, autonumber off | a numbered badge on each message (1. before the label in text) |
title text, accTitle, accDescr | the 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, oroptionoutside its block;- an
endwith nothing to close, or a block left open; createfor a participant already mentioned;- an
autonumberthat is notoffor 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 --> [*]
●
│
▼
╭───────╮
│ Still │
╰───┬───╯
│
push
▼
╭────────╮
│ Moving │
╰────┬───╯
│
▼
◉
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
| Syntax | Drawn as |
|---|---|
s1, state "Description" as s1, s1 : Description | a rounded state; more descriptions add lines |
s1 --> s2, s1 --> s2 : label | a 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 state | concurrent 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 note | a note beside the state, joined by a dashed line |
direction TB|BT|LR|RL | the diagram’s direction, or a composite state’s |
classDef, class s1,s2 name, s1:::name, style | colors and strokes, as in flowcharts |
%% comments, frontmatter title, accTitle, accDescr | as 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
┌──────────────────┐
│ «interface» │
│ Shape │
├──────────────────┤
├──────────────────┤
│ +area() : double │
└──────────────────┘
△
┆
┌─────┴─────┐
│ Circle │
├───────────┤
│ +double r │
├───────────┤
└───────────┘
In the editor a class diagram is read-only on the drawing side, as state diagrams are.
What is read
| Syntax | Drawn 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 id | members: 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 ()-- B | a lollipop interface: a small circle at the () end |
A "1" --> "*" B : label | cardinalities 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, style | as 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
}
┌──────────┐
│ CUSTOMER │
└──────────┘
1
places
*
┌──────────────────┐
│ ORDER │
├──────────────────┤
│ int id PK │
│ string status │
└──────────────────┘
In the editor an ER diagram is read-only on the drawing side, as state and class diagrams are.
What is read
| Syntax | Drawn 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 : label | the label in the middle; it may be quoted |
List~T~ in a type | List<T> |
direction, classDef, class A,B name, A:::name, style | as 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"
main │ develop ● │ init ├─● feature [beta] ● │ hotfix ◉─┘ release [v1.0]
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
| Syntax | Drawn as |
|---|---|
gitGraph, gitGraph LR:, gitGraph TB:, gitGraph BT: | lanes left to right, top to bottom, or bottom to top |
commit | a circle on the current branch |
commit id: "x" | the id x; without one, a stable generated id such as 0-2245cbe |
commit type: REVERSE / HIGHLIGHT | a crossed circle / a filled square (⊗ / ■ in text) |
commit tag: "v1" | a tag label ([v1] in text) |
branch name, branch name order: 2 | a new lane starting at the current commit |
checkout name, switch name | later 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
History of Social Media Platform
┌──────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐
│ 2002 │ │ 2004 │ │ 2005 │ │ 2006 │
└─────┬────┘ └─────┬────┘ └────┬────┘ └────┬────┘
──────┼────────────┼───────────┼───────────┼──────►
┌─────┴────┐ ┌─────┴────┐ ┌────┴────┐ ┌────┴────┐
│ LinkedIn │ │ Facebook │ │ YouTube │ │ Twitter │
└──────────┘ └─────┬────┘ └─────────┘ └─────────┘
┌─────┴────┐
│ Google │
└──────────┘
In the editor a timeline is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
timeline, timeline LR, timeline TD | periods left to right with events below, or top to bottom with events to the right |
title text | the title above (frontmatter title too) |
2002 : A : B | a period and its events |
: C on the next line | another event for the period above |
section name | a 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
Pets adopted by volunteers Dogs ███████████████████████████████▊ 79% Cats ███████ 17% Rats █▎ 3%
In the editor a pie chart is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
pie | slices largest first, clockwise from the top, with a legend to the right |
pie showData | each value in the legend (Dogs [386]) and in the text form |
title text | the title above, also on the header line (pie title Pets); frontmatter title too |
"label" : 42.5 | a 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
A Gantt Diagram
Section
A task ████████████████████████████████████
Another task ████████████████████████
Another
Task in Another ███████████████
another task ████████████████████████████
─────┬───────┬────────┬───────┬───────┬────────┬───────┬─────
2014-01-05 2014-01-19 2014-02-02 2014-02-16
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.
| Part | Values |
|---|---|
| tags | active, done, crit, milestone (a diamond), vert (a line across the chart) |
| START | a date, or after ID ID... (the latest of their ends); left out, the end of the task before |
| END | a date, a duration (3d, 1.5h, 2w, 30m, 10s, 500ms, 1M, 1y), or until ID ID... |
Settings
| Setting | Effect |
|---|---|
title, section NAME | the title, and a group of the tasks that follow |
dateFormat FORMAT | how dates are written, as dayjs reads them (default YYYY-MM-DD) |
axisFormat FORMAT | how the axis labels are written, in d3’s % codes (default %Y-%m-%d) |
tickInterval 1week | the axis step: a number and millisecond, second, minute, hour, day, week, or month |
excludes weekends, friday, 2014-01-15 | days a duration skips, shaded grey; a date is matched as written in dateFormat and as YYYY-MM-DD |
includes 2014-01-18 | days never excluded |
weekend friday | the weekend is Friday and Saturday (default saturday: Saturday and Sunday) |
weekday monday | the day weekly ticks fall on (default sunday) |
inclusiveEndDates | an END date includes that day |
todayMarker off or todayMarker stroke:#0f0,stroke-width:3px | hide or style the line at today |
topAxis | repeat 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
((mindmap))
├── Origins
│ ├── Long history
│ └── Popularisation
├── Research
│ ├── On effectiveness
│ │ and features
│ └── On Automatic creation
└── Tools
├── Pen and paper
└── Mermaid
In the editor a mindmap is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
| indentation | the tree: a node’s parent is the nearest line above it that is indented less |
text | the 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 b | classes on the node above, kept in the model |
frontmatter title | the 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
My working day Go to work Make tea ●●●●● 5 Me Go upstairs ●●●○○ 3 Me Do work ●○○○○ 1 Me, Cat Go home Go downstairs ●●●●● 5 Me Sit down ●●●●● 5 Me
In the editor a user journey is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
title text | the title above; frontmatter title too |
section name | a colored box over its tasks |
name: score: actor, actor | a task box with a dot per actor, and a face below it for the score |
accTitle, accDescr | kept 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]
Reach and engagement of campaigns
┌────────────────────┬────────────────────┐
│ Need to promote │ We should expand │
│ │ │
High Engagement │ Campaign F ● │ │
│ │ ● Campaign C │
│ Campaign A ● │ │
├────────────────────┼────────────────────┤
│ Re-evaluate │ May be improved │
│ Campaign E ● │ 1 │
Low Engagement │ Campaign B ● │ │
│ │ │
│ │ │
└────────────────────┴────────────────────┘
Low Reach High Reach
1 Campaign D
In the editor a quadrant chart is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
title text | the title above; frontmatter title too |
x-axis Low --> High | labels under the left and right halves; x-axis Low alone is centered |
y-axis Low --> High | labels beside the bottom and top halves; y-axis Low alone is centered |
quadrant-1 text to quadrant-4 text | labels 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: #f00 | a point’s own style |
Name:::cls: [x, y] and classDef cls color: #f00 | a style from a class; the point’s own styles win |
accTitle, accDescr | kept 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]
Sales Revenue
bar 1 line 1
jan ███▍ 5000 ● 5000
feb ██████▉ 6000 ● 6000
mar ████████████ 7500 ● 7500
apr ██████████████▍ 8200 ● 8200
may ██████████████████▉ 9500 ● 9500
jun ██████████████████████▎ 10500 ● 10500
jul ████████████████████████ 11000 ● 11000
aug █████████████████████▎ 10200 ● 10200
sep █████████████████▉ 9200 ● 9200
oct ███████████████▍ 8500 ● 8500
nov ██████████▎ 7000 ● 7000
dec ██████▉ 6000 ● 6000
Revenue (in $): 4000 to 11000
In the editor an XY chart is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
xychart-beta horizontal | categories 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 --> 10 | a numeric x-axis, with each series spread evenly across it |
y-axis "title" 0 --> 100 | the 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, accDescr | kept 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
┌──────────────────┐
│ «Element» │
│ test_entity │
├──────────────────┤
│ Type: simulation │
└─────────┬────────┘
┆
«satisfies»
▼
┌──────────────────────────────┐
│ «Requirement» │
│ test_req │
├──────────────────────────────┤
│ Id: 1 │
│ Text: the test text. │
│ Risk: High │
│ Verification: Test │
└──────────────────────────────┘
In the editor a requirement diagram is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
requirement name { ... } | a box with «Requirement» above the name and its fields below |
functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraint | the 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 - a | a dashed arrow from a to b labeled «satisfies»; also copies, derives, verifies, refines, traces |
a - contains -> b | a solid line from a circle at a |
"quoted name" | a name or value with :, -, or other punctuation |
name:::cls, class a,b cls, classDef, style | classes and styles, as in flowcharts |
direction LR | the 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]
┌─ Backlog ────────────────────────┐ ┌─ In Review ──────────────────────┐ ┌─ Done ───────────────────────────┐ │ ╭──────────────────────────────╮ │ │ ╭──────────────────────────────╮ │ │ │ │ │ Draft onboarding guide │ │ │ │ Fix login timeout │ │ │ │ │ │ ▼ Low @alex │ │ │ │ ▲▲ Very High BUG-101 @sam │ │ │ │ │ ╰──────────────────────────────╯ │ │ ╰──────────────────────────────╯ │ │ │ │ ╭──────────────────────────────╮ │ │ │ │ │ │ │ Quoted: card (with brackets) │ │ │ │ │ │ │ ╰──────────────────────────────╯ │ │ │ │ │ └──────────────────────────────────┘ └──────────────────────────────────┘ └──────────────────────────────────┘
In the editor a kanban board is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
| a node at the first node’s indent | a column, titled by its text |
| a node indented under a column | a 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 title | the title above |
frontmatter config.kanban.ticketBaseUrl | kept 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)"
UDP Packet
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
┌───────────────────────────────┬───────────────────────────────┐
0 │ Source Port │ Destination Port │
├───────────────────────────────┼───────────────────────────────┤
32 │ Length │ Checksum │
├───────────────────────────────┴───────────────────────────────┤
64 │ Data (variable length) │
└───────────────────────────────────────────────────────────────┘
In the editor a packet diagram is read-only on the drawing side.
What is read
| Syntax | Drawn 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 title | the title above |
frontmatter config.packet.bitsPerRow | bits per row, 32 by default |
frontmatter config.packet.showBits: false | no bit numbers |
frontmatter config.packet.bitOrder: descending | each row with its highest bit on the left |
packet-beta | the 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
Grades
Math Alice ████████████████████▍ 85
Bob ████████████████▊ 70
Science Alice █████████████████████▋ 90
Bob ██████████████████ 75
English Alice ███████████████████▎ 80
Bob ████████████████████▍ 85
History Alice ████████████████▊ 70
Bob ███████████████████▎ 80
Geography Alice ██████████████████ 75
Bob █████████████████████▋ 90
Art Alice █████████████████████▋ 90
Bob ████████████████████▍ 85
0 to 100
In the editor a radar chart is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
axis a["Label"], b | axes 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 0 | the values at the rim and the center; max defaults to the largest value, min to 0 |
ticks 5 | the number of rings |
graticule circle, graticule polygon | round rings, or rings with a corner on each axis |
showLegend false | no legend |
title text, frontmatter title | the title above |
frontmatter config.radar | width, 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
Household budget Salary, net $4200 └─ Budget $4200 ████████████████████████ Side work $600 └─ Budget $600 ███▍ Budget $4800 ├─ Rent $1800 ██████████▎ ├─ Savings $1200 ██████▉ ├─ Food $700 ████ └─ The "other" pile $1100 ██████▎ Rent $1800 Savings $1200 ├─ Index fund $900 █████▏ └─ Cash $300 █▊ Food $700 The "other" pile $1100 Index fund $900 Cash $300
In the editor a sankey diagram is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
source,target,value | a band from source to target as wide as the value; nodes are made on first use |
"a, b",c,1 | a quoted name may hold ,; "" is a literal " |
frontmatter title | the title above |
config.sankey.linkColor | gradient (the default), source, target, or a color such as "#a1a1a1" |
config.sankey.nodeAlignment | justify (the default), left, right, or center |
config.sankey.showValues | false leaves values out of the labels |
config.sankey.prefix, suffix | text around each value, e.g. "$" or " TWh" |
config.sankey | also 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
Housing $2,010.50 ██████████▎ ├─ Rent $1,800.50 █████████▏ └─ Utilities $210.00 █▏ Food $1,820.00 █████████▎ ├─ Dining $1,180.00 ██████ └─ Groceries $640.00 ███▎ Savings $900.00 ████▋
In the editor a treemap is read-only on the drawing side.
What is read
| Syntax | Drawn as |
|---|---|
"Name" | a section holding the items indented under it |
"Name": 10 or "Name", 10 | a leaf whose area is its value; , and _ in a value are ignored |
'Name' | single quotes work as well |
"Name": 10:::cls | a leaf or section styled by classDef cls (fill, stroke, stroke-width, color) |
title, frontmatter title | the title above |
accTitle, accDescr | read, not drawn |
config.treemap.valueFormat | a d3-format string such as ",.2f", "$,", ".1%", or ".2s" |
config.treemap.showValues | false leaves values out |
config.treemap | also 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
┌───┐ ┌───┐ ┌───┐ │ a │ │ b │ │ c │ └───┘ └───┘ └───┘ ┌──────────┐ ┌───┐ │ d │ │ e │ └──────────┘ └───┘
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
| Syntax | Drawn as |
|---|---|
columns 3, columns auto | the columns of the diagram or group; auto (the default) is one row |
a, a["Label"], a(("Label")), … | a block, with the flowchart shapes |
a:2 | a block 2 columns wide |
space, space:2 | an 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 … end | a group of blocks with its own columns |
a --> b, a -- "text" --- b, ==>, -.-> | an edge, drawn straight from block to block |
classDef, class, style | styles, on blocks and groups |
frontmatter title | the title above |
config.block.padding | the space between blocks (8) |
accTitle, accDescr | read, 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, 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
┌ API (cloud) ─────────────────────────────────────┐ │ │ │ ┌─────────────────┐ ┌─────────────────────┐ │ │ │ Server (server) ├──────┤ Database (database) │ │ │ └────────┬────────┘ └──────────┬──────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌───────┴────────┐ ┌───────┴────────┐ │ │ │ Storage (disk) │ │ Storage (disk) │ │ │ └────────────────┘ └────────────────┘ │ │ │ └──────────────────────────────────────────────────┘
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
| Syntax | Drawn 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 id | a point where edges meet |
... in group | inside that group; groups nest |
a:R -- L:b | an 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:b | an edge with arrows |
a:R -[label]- L:b | an edge with a label |
a{group}:R -- L:b | an edge from the side of a’s group |
align row a b, align column a b | the services kept in one row or column, in order |
title, frontmatter title | the title above |
accTitle, accDescr | read, 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")
Shop ╭────────────╮ │ <<person>> │ │ Customer │ ╰────────────╯ ┌ Shop [SYSTEM] ──────────────────────────┐ │ │ │ ╭───────────────╮ ╭──────────────────╮ │ │ │ <<container>> │ ├──────────────────┤ │ │ │ Web App │ │ <<container_db>> │ │ │ │ [Go] │ │ Database │ │ │ │ Serves pages │ │ [Postgres] │ │ │ ╰───────────────╯ ╰──────────────────╯ │ │ │ └─────────────────────────────────────────┘ user --> web: Uses [HTTPS] web --> db: Reads
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
| Syntax | Drawn as |
|---|---|
Person, System, Container, Component | a 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_Boundary | a dashed box titled at the top left with its kind |
Deployment_Node, Node, Node_L, Node_R | a solid box titled at the top left |
Rel, Rel_U, Rel_D, Rel_L, Rel_R, RelIndex | an arrow with its label and [technology] |
Rel_Back, BiRel | an arrow the other way, or both ways |
UpdateElementStyle, UpdateRelStyle | the colors given by $bgColor, $fontColor, $borderColor, $textColor, $lineColor |
UpdateLayoutConfig | $c4ShapeInRow elements and $c4BoundaryInRow boundaries per row |
title, frontmatter title | the title above |
accTitle, accDescr | read, 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)
}
Order service
┌───────────────┐ ┌───────┐
│ OrderService │ │ Repo │
└───────┬───────┘ └───┬───┘
│ │
create(item) │ │
─────────────►┃ │
┃ │
┃ save(item) │
├──────────────►┃
┃ │
order ┃ │
<┄┄┄┄┄┄┄┄┄┄┄┄┤ │
│ │
┌───────┴───────┐ ┌───┴───┐
│ OrderService │ │ Repo │
└───────────────┘ └───────┘
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
| Syntax | Drawn 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 A | a participant drawn as that symbol |
@Starter(A) | A as the caller of calls that name none |
A->B: text | an async message (an open arrowhead) |
@return or @reply before A->B: text | a dotted reply |
A.method(args), C->A.method(args) | a sync call from the current caller (or C), activating A |
... { ... } after a call | the statements inside, called from A |
x = A.method(), Type x = A.method() | a dotted reply x when the call ends |
return x | a 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 title | the title above |
// comment | read, 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
Late delivery
├── People
│ └── Short staffed
│ └── Holidays
├── Methods
└── Machines
└── Broken scanner
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
| Syntax | Drawn as |
|---|---|
| the first line | the effect, in the head |
| a line indented under another | a cause of that line |
<br> | a line break |
%% comment, frontmatter title | read; 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
Team overlap Frontend - React - Design Systems Backend - API Frontend & Backend: Shared - OpenAPI
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
| Syntax | Drawn 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 union | its size (a set’s default is 10) |
text A,B id["Label"], or text id indented under a set or union | text inside the region |
style ids fill:..., color:..., stroke:..., stroke-width:..., fill-opacity:... | those styles |
title, %% comment, frontmatter title | read; 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]
}
Storage Options
Visibility
│ ┆ ┆ ┆
│ ┆ ┆ ◆ App
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ■ Database
│ ● File System ● SQL DB ● NoSQL ● Cloud DB
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
│ ┆ ┆ ┆
└─────────────────────────────────────────────────────────────────
Genesis Custom Built Product Commodity
Evolution
Links:
App -- Database
Pipelines:
Database: File System, SQL DB, NoSQL, Cloud DB
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
| Syntax | Drawn as |
|---|---|
anchor Name [visibility, evolution] | bold text |
component Name [visibility, evolution] | a circle with its name |
label [x, y] after a component | its 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, ; label | links, dashed, with arrowheads, labeled |
evolve Name 0.8 | a red arrow to the new evolution |
pipeline Name { component X [evolution] } | a box of components under its parent |
evolution A -> B@0.4 -> C / D | stage names, at positions when given |
note, annotation, annotations, accelerator, deaccelerator | text, numbered circles with a list, arrows |
title, size [w, h], %% comment | read; 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
/
└── my-project/
├── src/
│ ├── App.tsx main component
│ └── index.js entry point
├── .env environment variables
├── Dockerfile
└── package.json
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
| Syntax | Drawn 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 |
:::highlight | a shaded row |
icon(file), icon(folder), icon() | that icon, or none |
## text | a description in italics, lined up right of the labels |
frontmatter treeView: rowIndent, paddingX, paddingY, lineThickness, showIcons | read |
title, %% comment | read; 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
┌─ Storefront ──────────────────────────────────────┐
│ ╭──────────────────╮ │
┌─┼────────────────────────────►( Browse catalogue ) │
│ │ ┌►( ) │
┌──────────┐ ┌──┘ │ ╭──────────╮ ┌┄«include»┄┘ ╰──────────────────╯ │
│ ├─┘ ┌─┼─►( Checkout ├┄┘ │
│ Customer ├────┘ │ ╰──────────╯ │
│ ├─┐ └───────────────────────────────────────────────────┘
└──────────┘ │
└──┐ ┌─ Fulfilment ─────────┐
│ │ ╭────────────────╮ │
└───────────────┼─►( Track delivery ) │
┌─────────┐ ┌───────────────┼─►( ) │
│ Support ├─────┘ │ ╰────────────────╯ │
└─────────┘ └──────────────────────┘
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
| Syntax | Drawn as |
|---|---|
actor A, actor A("label"), actor A, B | a stick figure |
@{ type: hollow }, @{ type: awesome } | a hollow outline, or a filled silhouette |
U("label"), U[label], "label", an undeclared endpoint | an 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 edge | an association with that marker |
-- label --> and the other labelled forms | a labelled association |
..> : include, ..> : extend | a 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, style | classes and styles |
direction, accTitle, accDescr, %% comment | read |
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 . ;
┌────────────┐
┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐ ┌────────┐ │ ┌────────┐ │
Identifier = ●─┤ ? !Keyword ? ├──┤ Letter ├──┼─┤ Letter ├─┼─●
└┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘ └────────┘ │ └────────┘ │
└──────◄─────┘
╭────╮
Keyword = ●─┬─┤ if ├────┬─●
│ ╰────╯ │
│ ╭──────╮ │
├─┤ else ├──┤
│ ╰──────╯ │
│ ╭───────╮ │
└─┤ while ├─┘
╰───────╯
┌┄┄┄┄┄┄┄┄┄┄┄┄┄┐ ┌┄┄┄┄┄┄┄┐
Any = ●─┤ ? &Letter ? ├──┤ ? . ? ├─●
└┄┄┄┄┄┄┄┄┄┄┄┄┄┘ └┄┄┄┄┄┄┄┘
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
| Notation | Syntax |
|---|---|
| all | name = ... ; 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]
┌─ Buyer ────────────────────────────────────────────────────────────────────────────────────────────────┐ │ ╭────────────────╮ ┌─────────────┐ │ │ ( Choose product ├─┐ ┌┄Invoice ready┄►│ Pay invoice ├━┓ │ │ ╰────────────────╯ │ ┆ └─────────────┘ ┃ │ ├─ Store ─────────────┼─────────────────────┼────────────────────────────────┼───────────────────────────┤ │ │ ┌───────────────┐ ┆ ┃ ╭──────╮ │ │ └──►│ Reserve stock ├┄┘ ┗━━►( Ship ├─┐ │ │ └───────────────┘ ╰──────╯ │ │ ├─────────────────────────────────────────────────────────────────────────────────────────┼──────────────┤ │ │ ┌───────┐ │ │ └──►│ Audit │ │ │ └───────┘ │ └────────────────────────────────────────────────────────────────────────────────────────────────────────┘
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 (
TBwhen 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"
Strategy Categorization ┌───────────────────────────┬────────────────────────────────┐ │ Complex ┆ Complicated │ │ Probe → Sense → Respond ┆ Sense → Analyse → Respond │ │ Emergent Practices ┆ Good Practices │ │ ┆ │ │ Market research ┆ Competitive analysis │ │ ┆ │ │ ┌─────┴─────┐ │ │ │ Confusion │ │ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ Disorder ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ └─────┬─────┘ │ │ ┃ │ │ Chaotic ┃ Clear │ │ Act → Sense → Respond ┃ Sense → Categorise → Respond │ │ Novel Practices ┃ Best Practices │ │ ┃ │ │ Crisis management ┃ Standard pricing │ └───────────────────────────┴────────────────────────────────┘ Complex → Complicated: Pattern identified Complicated → Clear: Best practice codified Clear → Chaotic: Complacency Chaotic → Complex: Stabilized
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(orcynefin-beta:) first, thentitle,accTitle, andaccDescras usual.- A domain keyword (
complex,complicated,clear,chaotic, orconfusion) 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 --> toadds a transition, with an optional: "label". A transition from a domain to itself is dropped, with a warning.showDomainDescriptions: falseunderconfig: 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
┌─────────────────────────────────────────────────────┐ │ │ │ UI/Automation ┌ 01 ui ─┐ │ │ │ CartUI │ │ │ └──────┬─┘ │ │ │ │ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤ │ ▼ │ │ Command/Read Model ┌ 02 cmd ─────────────┐ │ │ │ AddItem │ │ │ ├─────────────────────┤ │ │ │ description: string │ │ │ └───────────────┬─────┘ │ │ │ │ ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┤ │ ▼ │ │ Events ┌ 03 evt ───┐ │ │ │ ItemAdded │ │ │ └───────────┘ │ │ │ └─────────────────────────────────────────────────────┘
See crates/sirene-core/tests/fixtures/eventmodel/ for more. In the editor an event modeling
diagram is read-only on the drawing side.
Syntax
eventmodelingfirst, thentitle,accTitle, andaccDescras usual. Comments are%%,//, or/* ... */.tf NN type Name(ortimeframe) adds a time frame.NNis a frame number of one to three digits, unique in the diagram.typeisui,pcr(processor),cmd(command),rmo(readmodel), orevt(event).rf NN type Name(orresetframe) adds a reset frame, which takes no inferred relation.- After the name:
->> NNrelations 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 { ... }, andgwt 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
┌─ Planner ────────────────────────────────────┐ ┌─ Workers ───────────────────────┐
│ ╱───────────────────╲ │ │ ┌┬────────────┬┐ ┌───────┐ │
│ ┌───────────────┐ │ Split into tasks? ├──┼───yes───┼─►││ Web search │├───►│ Notes ├┄┄┼┄┐
╭──────╮ ┌─┼─►╱ Read the goal ├───►│ ├──┼─┐ │ └┴────────────┴┘ └───────┘ │ └┄┄┐ ╭─────────────╮
│ User ├────┘ │ └───────────────┘ ╲───────────────────╱ │ └─no──┐ │ │ └┄┤ Message bus │
│ │x┐ └──────────────────────────────────────────────┘ │ │ ╱──────────────╲ │ ┌─┤ │
╰──────╯ │ └─┼─►< Draft answer > │ ┌──┘ ╰─────────────╯
└─────────────────────────────────────────────────────────────┼──┤ >◄──────────────┼─┘
│ ╲──────────────╱ │
└─────────────────────────────────┘
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"] ... endgroups nodes;flow idand a barefloware untitled. Flows nest, andflow id["Title"]@{ view: collapsed }draws one as a single node.global ... endholds nodes that belong to no flow.connector id["Title"]declares a rounded node; without a title its label is its id.subgraphis an error.
Shapes and edges
- A node is a rounded rectangle unless its brackets or
@{ shape }say otherwise.{},{{}},[[]], and[/ /]keep their flowchart shapes. @{ shape }takestask,tool,input,decision,refdoc, andaction, 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]
}
┌─────────────────┐ ╭─────────────────╮
│ Dog │ │ Cat │
├─────────────────┤ ├─────────────────┤
│ + bark() : void │ │ + meow() : void │
└────────┬────────┘ ╰────────┬────────╯
│ │
└───┐ ┌──┘
│ │
│ │
└──┐ ┌───┘
▽ ▽
┌─────────────────┐
│ Animal │
├─────────────────┤
│ + name : string │
│ + age : int │
├─────────────────┤
│ + die() : void │
└─────────────────┘
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
| Syntax | Drawn as |
|---|---|
digraph, graph, strict | arrows 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, bgcolor | the direction, the title, and the background |
shape | the nearest sirene shape; record and Mrecord as compartments |
style | filled, rounded (nodes only; clusters stay square, with a warning), dashed, dotted, bold, invis |
color, fillcolor, fontcolor, penwidth | border, fill, text color, line width |
label, headlabel, taillabel | labels, with \n, \l, \N, \G, \E, \T, \H |
arrowhead, arrowtail, dir, minlen | end markers, which ends have them, and rank span |
rank=same, min, max, source, sink | nodes sharing a rank, or in the first or last |
constraint=false, group, ordering | edges that do not rank, straight edges in a group, source order |
compound=true with lhead, ltail | edges ending at a cluster’s border |
a:e, a:p, tailport, headport | compass ports; record ports with rankdir=LR or RL |
HTML <TABLE> node labels | compartments, 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
o /|\ ┌─────────┐ / \ │ Server │ User └────┬────┘ │ │ │ log in │ ├─────────►│ │ │ │ token │ │◄┄┄┄┄┄┄┄┄┄┤ │ │ o ┌────┴────┐ /|\ │ Server │ / \ └─────────┘ User
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
| Kind | Start |
|---|---|
| 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 |
| Network | nwdiag { ... } 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:
| Crate | What |
|---|---|
sirene-core | the parser, model, edits, layout, and SVG, PNG, and ASCII renderers; no GUI |
sirene-gui | the editor, on gpui and GPUI Kit |
sirene | the binary; the gui feature (on by default) links sirene-gui |
xtask | packaging 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:
- Set
versionin the rootCargo.toml, and the matching[workspace.dependencies]pins, toX.Y.Z. - Add a
## [X.Y.Z]section toCHANGELOG.md. - 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.