Cascadia documentation

Cascadia diagrams are written in plain Mermaid. There is no separate Cascadia language: what you type is exactly what Mermaid renders, and a diagram copied out of Cascadia works in any other Mermaid tool, and the other way round. Cascadia adds one directive of its own, %% @import, which other Mermaid tools read as a comment.

Getting started

Open Cascadia and sign in with Google or GitHub. Your account is created the first time you sign in, and Cascadia never sees your password.

To start a diagram, choose New (+) in the Files sidebar:

• New Diagram opens a short sequence diagram to edit.
• New from Template… opens a gallery with a starter diagram for every supported type.
• New Document opens a Markdown document.

Cascadia saves a moment after you stop typing, and ⌘S (Ctrl+S) saves at any time.

Writing diagrams

The first line names the diagram type, and everything after it follows that type’s Mermaid syntax.

sequenceDiagram
    participant Client
    participant API
    Client->>API: Place order
    API-->>Client: 201 Created

Comments start with %% and run to the end of the line. Frontmatter (--- blocks) and %%{init}%% directives configure a diagram as they do in Mermaid.

Cascadia supports 23 diagram types: flowchart, sequence, class, state, entity relationship, Gantt, pie, mindmap, user journey, Git graph, quadrant, XY chart, requirement, C4, timeline, Sankey, block, packet, kanban, architecture, radar, treemap and Venn. Each has a starter template. Diagram types lists the first line of each and what the editor does with it.

The editor

The code panel is a Monaco editor that understands Mermaid. Everything in it runs in your browser: code is never sent anywhere to be checked or fixed.

• Highlighting and completion for diagram types, keywords and arrows.
• Error markers. A moment after you stop typing, Mermaid parses the code. The line its parser stopped at is underlined, and the message under the preview links to the line and to Mermaid’s syntax page for the diagram type.
• Quick fixes for common mistakes. See Mermaid quick fixes.
• Quick Insert offers snippets for the most-used diagram types, and the starter templates.
• Formatting. ⇧⌥F or ⇧⌘B (Shift+Alt+F or Ctrl+Shift+B) tidies the indentation of blocks.

The preview renders as you type. Click a label in the preview to select the line that drew it; move the cursor in the code and the preview highlights what that line draws.

For flowchart, sequence, class and entity relationship diagrams you can also edit in the preview: double-click a label drawn as text to rename it, drag from the handle on a box to another box to connect them, and in a sequence diagram drag the end of a message to another participant. Every edit in the preview is a change to the code, so undo and version history cover it.

Mermaid quick fixes

When Mermaid code has an error, the editor marks the line Mermaid’s parser stopped at. For common mistakes it also offers a fix: press ⌘. (Ctrl+. on Windows and Linux) on that line, choose Quick Fix… in the error’s hover, or click the lightbulb beside the line.

A fix is applied only when you choose it, as one step that a single ⌘Z (Ctrl+Z) undoes. Fixes are worked out in the browser from the text alone; the code never leaves the browser. Errors without a fix still show their marker and message.

Starter templates

New from Template… opens a gallery with one starter diagram for each of the 23 supported types. Each entry has a name, a one-line purpose, a preview of its code and a link to Mermaid’s syntax page for the type. Type to filter the list, use the arrow keys to move through it, and press Return to use the highlighted template.

From the New menu, a template becomes a new diagram. From Quick Insert, it goes into the open diagram if that diagram is empty, and becomes a new diagram otherwise; a template never replaces code that is already there. The templates use plain Mermaid only, so they render the same in other Mermaid tools.

Imports between diagrams

%% @import "<diagram id or slug>" as "<label>"

An import stands for another Cascadia diagram you can open, so a shared flow lives in one diagram instead of being copied into many. In a sequence diagram it is drawn as a labelled block across the participants it involves; double-click the block in the preview to open the imported diagram. In other diagram types the line stays a comment. Because it starts with %%, other Mermaid tools ignore it.

sequenceDiagram
    participant Web
    participant Checkout
    %% @import "payments-flow" as "Payments"
    Web->>Checkout: Submit cart

Markdown documents

A document is Markdown with Mermaid diagrams in fenced code blocks, so design notes and their diagrams stay together. The code panel edits the Markdown, and the preview shows the prose with each diagram rendered in place.

# Checkout

Orders are confirmed before payment is taken.

```mermaid
flowchart LR
    Cart --> Confirm --> Pay
```

Choose New Document in the New menu to start one. Any diagram whose code contains a ```mermaid block is shown as a document.

Files and folders

The Files sidebar lists your diagrams and documents. Create folders from the New menu, drag a diagram onto a folder to move it, search by name, and sort by name or date. Shared with You lists the diagrams other people have added you to.

Version history

Every save that changes the code becomes a version. History lists them with their dates. Choose a version to compare it with the diagram as it is now, either as a code diff or as the rendered diagram before and after. Restore Version brings an earlier version back as a new version, so the history between them is kept.

If someone else saved the diagram after you opened it, your save does not overwrite theirs. Cascadia shows both versions side by side, so you can keep yours, use theirs, or edit the two into one and save that.

Sharing

Choose Share in the toolbar to decide who can open a diagram. Each diagram is private until its owner shares it.

• Anyone with the link can have no access, view, or edit. A diagram shared for viewing opens without signing in. Editing always needs a signed-in account, and Can edit lets anyone signed in who has the link make changes.
• People are added by the e-mail address they sign in with, as viewers (Can view) or editors (Can edit). They find the diagram under Shared with You.

Only the owner can change who has access or delete the diagram.

Exporting

Export in the toolbar offers:

• Mermaid Source (.mmd), the code as you wrote it.
• SVG Image.
• PNG Image, at twice the diagram’s size, on the theme’s background, white, or transparent.
• SVG for Visio, an SVG prepared for Microsoft Visio.
• Visio (.vsdx), a Visio drawing. A sequence diagram can also be exported as a native Visio sequence drawing.
• Copy as PNG and Copy SVG Markup, to the clipboard.
• All Diagrams (.zip), the Mermaid source and details of every diagram you own, in one archive.

Unsaved edits

Your latest edits are also kept in this browser until they are saved. If a save does not reach the server, because the connection dropped or the tab closed first, nothing you typed is lost: the next time you open the diagram in this browser, Cascadia offers the edits back to restore or discard. Diagrams are stored on the server, so opening and saving them needs a connection.