Getting started

A Siren document (.srn) is a Mermaid diagram, optionally followed by a timeline: block that describes the animation. A document without timeline: is a static diagram; with one, each press of Next moves it forward one step. One diagram can also carry several named blocks, timeline <name>:, each telling its own story; see Several timelines in one document.

flowchart TB
  A[Start] --> B[Fetch data]
  B --> C[Publish]

timeline:
  enter B fade, enter A-B fade
  enter C fade, enter B-C fade
  highlight C glow

Elements the timeline: never mentions are visible from the start; an element with an enter stays hidden until its step. For the full syntax, see Timeline block.

Try it right away in the Playground.

Using it in a web page

Siren ships as two npm packages; the source for both is on GitHub:

Package Purpose
siren-board A ready-made player: one line puts it on a page, with step buttons and a step counter, playback at an interval you pick, a full-diagram view, a switch between named timelines, dragging and zooming with a Reset view button, fullscreen (where a click on the diagram steps forward), and a dot grid behind the diagram.
siren-core The renderer itself: draws the document as SVG and returns a controller for the steps; you build the controls.

To put a diagram on a page as is, use siren-board:

npm install siren-board siren-core
import { createBoard } from "siren-board";
import "siren-core/theme.css";

createBoard(document.getElementById("board"), { source });

The player fills its container, so the container must have a height, or you will see nothing. The theme CSS comes from siren-core and holds the whole look of the diagram, so install both packages.

To build your own controls, use siren-core directly:

import { render } from "siren-core";
import "siren-core/theme.css";

const container = document.getElementById("diagram");
const { svg, controller, diagnostics } = render(source, container);

if (svg === null) {
  for (const d of diagnostics) console.error(`${d.line}:${d.column} ${d.message}`);
} else {
  document.getElementById("next").onclick = () => controller.next();
  document.getElementById("prev").onclick = () => controller.prev();
}

render() plays a document’s first timeline. To play another named one, pass { timeline: "name" } as a third argument; the result’s timelines lists the names the document declares.

Both packages need the DOM and run in the browser. For use without a bundler, loading from a CDN, and the full API, see the siren-board and siren-core READMEs.

Document structure

  1. The first non-blank line is the diagram header, which decides what kind of diagram the document is (see the table below). A Mermaid frontmatter (--- … ---) may come before it; see Differences from Mermaid shared by all diagrams.
  2. Next comes the diagram body, in the same syntax as Mermaid.
  3. Last come the optional timeline blocks: one unnamed timeline:, or several named timeline <name>: (lowercase, nothing after the colon). Everything from the first header to the end of the file is timeline, so the blocks must come last.

In the diagram body, only a whole line is a comment: a line whose first non-blank characters are %%, as in Mermaid. A %% in the middle of a line is not a comment. Inside a label or other text it is kept as text (A[50 %% done] draws “50 %% done”); after a complete statement (A --> B %% note) it is in most diagrams an error, which tells you to move the comment to a line of its own. Two diagrams read it as Mermaid does instead: a state diagram drops a %% and the rest of its line after a state, a transition, a brace, [*] or direction (A --> B %% note draws the transition), while a label, description or note still keeps it as text; a class diagram does the same after a relationship only on the document’s last line, and refuses it on any other. A comment line needs text after its %%: a line of only %% is refused in flowcharts and ER diagrams, so write %% text or leave the line blank. Inside a timeline block, %% still starts a comment anywhere on a line.

Supported diagrams

Diagram Header Docs
Flowchart flowchart TB, graph LR, etc. Flowchart
Class diagram classDiagram, classDiagram-v2 Class diagram
Sequence diagram sequenceDiagram Sequence diagram
State diagram stateDiagram, stateDiagram-v2 State diagram
ER diagram erDiagram ER diagram
Gantt chart gantt Gantt chart

Other Mermaid diagrams (pie, git graph, mindmap, and so on) are not supported yet; writing one reports an error on the first line.

Reading error messages

Siren’s rule is: whatever Mermaid can draw, Siren must draw too; syntax that is not supported yet is reported as an error rather than silently drawn wrong. Messages come in two severities:

  • Whole document rejected: the syntax cannot be understood, for example Unrecognized flowchart line: "...", or a malformed timeline. Nothing is drawn; only the error is shown.
  • One line dropped: the syntax is valid but the content has a problem, for example a timeline naming an id that does not exist, a click with a disallowed URL, or a class applied without being defined. The diagram is still drawn; only that line is skipped, with an error or warning attached.

Every message carries a line number, and the Playground marks it on the matching line in the editor.

Differences from Mermaid shared by all diagrams

These apply to every diagram:

  • A frontmatter is read but not applied yet. A leading --- … --- is read as Mermaid reads it: only at the very top, closed by the first --- at the same indent, YAML inside. Its config (theme, themeVariables, and so on) and title are kept, but nothing in them changes the drawing yet; each setting is reported as a warning at the opening fence, and the diagram is drawn without it. Only look: classic passes without a warning, since that is how Siren draws, and so does a top-level siren: key: Mermaid ignores it, Siren does not check it, and render() hands its value back as siren for the page to use. This site’s Playground keeps a diagram’s color settings there; see Themes. A frontmatter that is not valid YAML is an error. Use the --siren-* design tokens for appearance instead; see Themes.
  • %%{init: ...}%% directives are read the same way. One line or several, init and initialize alike, merged in order over the frontmatter’s config, and %%{wrap}%% too: read, kept, not applied, each setting a warning. An init that is not valid JSON is reported, and then, as in Mermaid, no init in the document is read. Any other %%{...}%% directive is removed with a warning.
  • Error messages do not mention Mermaid. Each says what is wrong and what to write instead.
  • The header cannot end with a semicolon: graph TD; is rejected; write graph TD.
  • On this site, a Style takes over the document’s colors. In the Playground and on the example pages, what a style, classDef/class/:::name or linkStyle sets for fill, stroke, color and the like is repainted in the chosen Style’s colors, such as Siren’s; a Custom theme does the same with colors of its own. Only colors inside a label’s own markup are drawn as written. siren-core on your own page draws it as written. See Themes.