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
- 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. - Next comes the diagram body, in the same syntax as Mermaid.
- Last come the optional timeline blocks: one unnamed
timeline:, or several namedtimeline <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
clickwith 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. Itsconfig(theme,themeVariables, and so on) andtitleare 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. Onlylook: classicpasses without a warning, since that is how Siren draws, and so does a top-levelsiren:key: Mermaid ignores it, Siren does not check it, andrender()hands its value back assirenfor 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,initandinitializealike, 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; writegraph 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/:::nameorlinkStylesets 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-coreon your own page draws it as written. See Themes.