Diagrams

blackbear draws diagrams from Mermaid, a way of writing diagrams as plain text that many apps read. In a note or a doc, write the diagram in a code block marked mermaid, and on a slide use Add diagram. To arrange a note's diagram by hand, open it as a canvas. Pax can write diagrams for you too.

blackbear draws them with its own engine, in your theme. The text stays plain Mermaid, so other apps can still draw it. When blackbear can't draw a diagram, the text stays on screen with the reason under it, and on a slide the diagram editor also says when part of a diagram was left out. For where to write one, see the Notes, Docs, Slides and Canvas guides.

Each kind below has an example and notes on what blackbear reads. After them come the shapes and arrows they use, then the kinds blackbear doesn't draw.

Flows and systems

Flowchart Boxes joined by lines and arrows, for a process, a decision or how parts connect.

Start with flowchart or graph.

The example below, drawn as a flowchart The example below, drawn as a flowchart
flowchart LR
  Draft([Write a draft]) --> Ready{Ready?}
  Ready -- Yes --> Publish[(Publish)]
  Ready -- Not yet --> Draft
  • The word after the header sets the direction, TB or TD for top to bottom, BT for bottom to top, LR for left to right and RL for right to left.
  • graph works as the header too.
  • subgraph and end put nodes in a titled box, and a line may point at the box itself.
  • direction LR (or TB, BT, RL) inside a subgraph lays that box out its own way, as long as lines from outside point at the box itself.
  • When a line from outside reaches a node inside the box, the box follows the diagram's direction, as Mermaid draws it.
  • Shapes come from the brackets around a node's text or from @{ shape: ... }, as listed under Shapes.
  • Put text that has brackets in it inside double quotes, as in A["Totals (by month)"].
  • style, classDef, class and ::: color a node or a subgraph in the theme color nearest the one written: red reads as danger, orange and yellow as warning, green as success, blue as info and purple or pink as accent, and grays keep the default. A class named after a role, as in A:::accent, is that role. Exact shades, text colors and fonts follow your theme, so the diagram reads in light and dark.
  • linkStyle colors lines the same way, counting them from 0 in the order they are written (or default for all of them). stroke-dasharray dashes a line and a stroke-width of 3px or more draws it thick.
  • click lines are left out.
State diagram The states something moves through and what moves it between them.

Start with stateDiagram-v2 or stateDiagram.

The example below, drawn as a state diagram The example below, drawn as a state diagram
stateDiagram-v2
  [*] --> Draft
  Draft --> Review : submit
  Review --> Draft : changes asked
  Review --> Published : approve
  Published --> [*]
  • [*] is where it starts, or where it ends when it comes after an arrow.
  • state Name { ... } holds states of its own, drawn inside a box.
  • -- inside state Name { ... } divides it into regions that run at the same time, side by side with a dashed line between them, each with its own [*].
  • A note sits beside its state, on the side it names: note left of X : text, or note right of X with lines that end at end note.
  • A floating note, note "text" as N, draws as a note of its own.
Block diagram Blocks laid out in a grid of columns you choose, in the order you write them.

Start with block or block-beta.

The example below, drawn as a block diagram The example below, drawn as a block diagram
block
  columns 3
  inbox["Inbox"] sort["Sort"] archive[("Archive")]
  notes["Notes"]:2 tasks["Tasks"]
  inbox --> sort
  sort --> archive
  • columns 3 sets how many blocks fit in a row, and name:2 makes a block two columns wide.
  • space, or space:2, leaves cells empty.
  • block:name ... end nests a block with a grid of its own.
  • name<["text"]>(right) draws a block arrow. It also points left, up or down, and x and y point both ways.
Architecture Services and the groups they run in, with each line leaving and entering from the side you name.

Start with architecture-beta.

The example below, drawn as a architecture The example below, drawn as a architecture
architecture-beta
  group cloud(cloud)[Cloud]
  service api(server)[API] in cloud
  service db(database)[Database] in cloud
  service web(internet)[Website]
  web:R --> L:api
  api:R --> L:db
  • The icons database, disk, server, cloud and internet draw their picture.
  • Any other icon name draws a plain square.
  • a:R --> L:b leaves a from its right side and enters b from its left, which also puts b to the right of a. The sides are L, R, T and B.
  • junction adds a point where lines meet, and align row or align column lines services up.

Time and messages

Sequence diagram Messages passed between people or systems, in the order they happen.

Start with sequenceDiagram.

The example below, drawn as a sequence diagram The example below, drawn as a sequence diagram
sequenceDiagram
  participant P as Phone
  participant S as Server
  P->>S: Sign in
  activate S
  S-->>P: Session
  deactivate S
  loop Every minute
    P->>S: Send changes
  end
  • participant or actor names each column, and as gives it a longer name.
  • loop, alt with else, opt, par with and, critical with option, break and rect draw a frame around their messages.
  • activate and deactivate, or + and - after an arrow, draw a bar while a participant is busy.
  • autonumber numbers the messages.
  • Note right of, left of or over a participant adds a note.
  • box ... end groups participants under a title.
  • create participant C right before a message to C draws C's box where that message reaches it; destroy C before a message from or to C ends C's lifeline there with a cross.
Timeline Periods in order, each with what happened in it.

Start with timeline.

The example below, drawn as a timeline The example below, drawn as a timeline
timeline
  title Moving house
  section Before
    March : Find a place
    April : Pack : Book the van
  section After
    May : Unpack
  • Each line is a period, then its events after colons. A line that starts with a colon adds to the period above.
  • section groups the periods after it.
Git graph A history of commits on branches, as Git records it.

Start with gitGraph.

The example below, drawn as a git graph The example below, drawn as a git graph
gitGraph
  commit id: "start"
  branch feature
  commit id: "draft"
  checkout main
  commit id: "fix"
  merge feature tag: "v1.0"
  • commit, branch, checkout (or switch), merge and cherry-pick replay the history in order.
  • A commit takes an id:, a tag: and a type:, which is NORMAL, REVERSE or HIGHLIGHT.
  • gitGraph TB: draws it from top to bottom.
  • In the front matter, config.gitGraph reads mainBranchName, mainBranchOrder, showBranches, showCommitLabel and parallelCommits.
  • A history Mermaid would refuse, such as merging a branch with nothing new in it, is refused with Mermaid's reason.

Models and specs

Class diagram Classes with their fields and methods, and how they relate.

Start with classDiagram or classDiagram-v2.

The example below, drawn as a class diagram The example below, drawn as a class diagram
classDiagram
  class Note {
    +String title
    +String body
    +save()
  }
  class Folder {
    +String name
  }
  Folder "1" o-- "*" Note : holds
  Note <|-- DailyNote
  • The ends say what a relation is. <|-- inherits, *-- is composed of, o-- aggregates and --> points, and .. in place of -- draws it dashed.
  • () at an end marks a lollipop interface. In Shape ()-- Circle the line from Circle ends in an open circle with Shape's name beside it.
  • Text in quotes beside an end is its multiplicity, and text after a colon labels the line.
  • <<interface>> above a class and ~T~ in its name (drawn as <T>) are kept.
  • namespace Name { ... } draws its classes in a box.
  • A dotted name such as namespace Company.Engineering draws a box for each part, one inside the other, as Mermaid 12 does. With front matter config: class: hierarchicalNamespaces: false, each namespace gets its own box under its full name.
  • note for A "text" adds a note tied to a class.
Entity relationship diagram The things a database keeps, their attributes, and how many of one go with another.

Start with erDiagram.

The example below, drawn as a entity relationship diagram The example below, drawn as a entity relationship diagram
erDiagram
  PERSON ||--o{ NOTE : writes
  NOTE }o--o{ TAG : has
  PERSON {
    string name
    string email UK
  }
  NOTE {
    string id PK
    string title
  }
  • Each end is drawn in crow's-foot notation. || is exactly one, |o zero or one, }| one or more and }o zero or more.
  • The spelled-out forms read too, such as only one to zero or more.
  • -- draws a solid line and .. a dashed one.
  • Attributes take a type and a name, then PK, FK or UK, then a comment in quotes.
Requirement diagram Requirements, the things that meet them, and how they trace to each other.

Start with requirementDiagram.

The example below, drawn as a requirement diagram The example below, drawn as a requirement diagram
requirementDiagram
  requirement offline {
    id: 1
    text: Notes open without a connection.
    risk: high
    verifymethod: test
  }
  element app {
    type: software
  }
  app - satisfies -> offline
  • The kinds are requirement, functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement and designConstraint, plus element.
  • contains draws a solid line with a circled cross at the container. satisfies, verifies, derives, refines, traces and copies draw a dashed arrow.
C4 diagram A software system at the level you choose, from the people who use it down to its components.

Start with C4Context, C4Container, C4Component, C4Dynamic or C4Deployment.

The example below, drawn as a c4 diagram The example below, drawn as a c4 diagram
C4Context
  title Notes app
  Person(you, "You", "Writes notes")
  System(app, "Notes app", "Keeps notes on your devices")
  System_Ext(mail, "Email", "Sends sign-in links")
  Rel(you, app, "Writes in")
  Rel(app, mail, "Sends links through")
  • Person, System, Container and Component also come as Db for a store, Queue for a queue and _Ext for something outside.
  • Boundaries and deployment nodes draw a box around what their { ... } holds, and they nest.
  • Rel, BiRel and Rel_Back draw a relationship. In C4Dynamic they are numbered in order.
  • $bgColor, $borderColor and $lineColor, on an element or a relationship or in UpdateElementStyle and UpdateRelStyle, draw in the theme color nearest the one written, as flowchart styles do. UpdateRelStyle colors the first relationship written between its two names.
  • $offsetX and $offsetY aren't needed: Blackbear places each label clear of other labels and lines.
  • A shape word in $shape or $tags, such as database or queue, gives an element that shape.
  • UpdateLayoutConfig is passed over: Blackbear lays the diagram out itself.
Packet diagram The fields of a network packet or any record of bits, in rows with their bit numbers.

Start with packet or packet-beta.

The example below, drawn as a packet diagram The example below, drawn as a packet diagram
---
config:
  packet:
    bitsPerRow: 16
---
packet
  0-15: "Source port"
  16-31: "Destination port"
  32-47: "Length"
  48-63: "Checksum"
  • A field is a range (0-15), a single bit (16) or +8 for the next 8 bits.
  • In the front matter, config.packet sets bitsPerRow (32 unless you set it) and bitOrder, ascending or descending.

Ideas and boards

Mind map One idea in the middle and everything that branches from it.

Start with mindmap.

The example below, drawn as a mind map The example below, drawn as a mind map
mindmap
  root((Trip))
    Travel
      Train
      Bus
    Stay
      Hotel
    Plans
      Museum
      Hike
  • Indentation sets the level. The first line is the center, and there is only one.
  • Brackets set a shape: [square], (rounded), ((circle)), ))bang((, )cloud( and {{hexagon}}.
  • ::icon lines are left out.
Kanban board Columns of cards, such as to do, doing and done.

Start with kanban.

The example below, drawn as a kanban board The example below, drawn as a kanban board
kanban
  Todo
    a[Write the outline]
  Doing
    b[Draft the intro]@{ assigned: 'Sam', priority: 'High' }
  Done
    c[Pick a topic]
  • Columns sit at one indent and their cards one level deeper, in the order you write them.
  • @{ ticket: ..., assigned: ..., priority: ... } shows under the card's text, and label: replaces the text.

Shapes

In a flowchart, the brackets around a node's text set its shape, as in A[(Orders)]. Every shape also has names you can give in A@{ shape: cyl, label: "Orders" }, and each name on a card draws the same shape. The last 7 are drawn without their text.

A step. A step.

rect A[Text]

A step.

Also proc, process, rectangle, squarerect

An event. An event.

rounded A(Text)

An event.

Also event, roundedrect

A start or an end. A start or an end.

stadium A([Text])

A start or an end.

Also terminal, pill

A step described elsewhere. A step described elsewhere.

fr-rect A[[Text]]

A step described elsewhere.

Also subprocess, subproc, framed-rectangle, subroutine

A database. A database.

cyl A[(Text)]

A database.

Also db, database, cylinder

A circle around the text. A circle around the text.

circle A((Text))

A circle around the text.

Also circ

A stop. A stop.

dbl-circ A(((Text)))

A stop.

Also double-circle, doublecircle

A decision. A decision.

diam A{Text}

A decision.

Also decision, diamond, question

Getting ready, or a condition. Getting ready, or a condition.

hex A{{Text}}

Getting ready, or a condition.

Also hexagon, prepare

Input or output. Input or output.

lean-r A[/Text/]

Input or output.

Also lean-right, in-out

Output or input. Output or input.

lean-l A[\Text\]

Output or input.

Also lean-left, out-in

A priority step. A priority step.

trap-b A[/Text\]

A priority step.

Also priority, trapezoid-bottom, trapezoid

A step done by hand. A step done by hand.

trap-t A[\Text/]

A step done by hand.

Also manual, trapezoid-top, inv-trapezoid

A box notched in on its left. A box notched in on its left.

odd A>Text]

A box notched in on its left.

A data store. A data store.

datastore

A data store.

Also data-store

Disk storage. Disk storage.

lin-cyl

Disk storage.

Also disk, lined-cylinder

Direct access storage, or a queue. Direct access storage, or a queue.

h-cyl

Direct access storage, or a queue.

Also das, horizontal-cylinder

A document. A document.

doc

A document.

Also document

Several documents. Several documents.

docs

Several documents.

Also documents, st-doc, stacked-document

A document with a line down its side. A document with a line down its side.

lin-doc

A document with a line down its side.

Also lined-document

A tagged document. A tagged document.

tag-doc

A tagged document.

Also tagged-document

A wait. A wait.

delay

A wait.

Also half-rounded-rectangle

A card. A card.

notch-rect

A card.

Also card, notched-rectangle

Where a loop starts or stops. Where a loop starts or stops.

notch-pent

Where a loop starts or stops.

Also loop-limit, notched-pentagon

A step in parts. A step in parts.

div-rect

A step in parts.

Also div-proc, divided-rectangle, divided-process

A shaded step. A shaded step.

lin-rect

A shaded step.

Also lined-rectangle, lined-process, lin-proc, shaded-process

A tagged step. A tagged step.

tag-rect

A tagged step.

Also tagged-rectangle, tag-proc, tagged-process

Internal storage. Internal storage.

win-pane

Internal storage.

Also internal-storage, window-pane

Typing something in. Typing something in.

sl-rect

Typing something in.

Also manual-input, sloped-rectangle

Several steps. Several steps.

st-rect

Several steps.

Also procs, processes, stacked-rectangle

Paper tape. Paper tape.

flag

Paper tape.

Also paper-tape

Stored data. Stored data.

bow-rect

Stored data.

Also stored-data, bow-tie-rectangle

A display. A display.

curv-trap

A display.

Also curved-trapezoid, display

Taking something out. Taking something out.

tri

Taking something out.

Also extract, triangle

A file kept by hand. A file kept by hand.

flip-tri

A file kept by hand.

Also manual-file, flipped-triangle

A comment. A comment.

braces

A comment.

A comment, its brace on the left. A comment, its brace on the left.

brace

A comment, its brace on the left.

Also brace-l, comment

A comment, its brace on the right. A comment, its brace on the right.

brace-r

A comment, its brace on the right.

Text on its own. Text on its own.

text

Text on its own.

A cloud. A cloud.

cloud

A cloud.

A burst. A burst.

bang

A burst.

A start. A start.

sm-circ

A start.

Also start, small-circle, statestart

A junction. A junction.

f-circ

A junction.

Also junction, filled-circle

A stop. A stop.

fr-circ

A stop.

Also stop, framed-circle, stateend

A summary. A summary.

cross-circ

A summary.

Also summary, crossed-circle

Paths splitting or joining. Paths splitting or joining.

fork

Paths splitting or joining.

Also join, forkjoin

Gathering things together. Gathering things together.

hourglass

Gathering things together.

Also collate

A communication link. A communication link.

bolt

A communication link.

Also com-link, lightning-bolt

Lines

The links between nodes in a flowchart.

WriteDraws
A --> B An arrow. An arrow.

An arrow.

A --- B A line without an arrow. A line without an arrow.

A line without an arrow.

A <--> B Arrows at both ends. Arrows at both ends.

Arrows at both ends.

A -.-> B A dotted arrow. A dotted arrow.

A dotted arrow.

A ==> B A thick arrow. A thick arrow.

A thick arrow.

A --o B A circle at the end. A circle at the end.

A circle at the end.

A --x B A cross at the end. A cross at the end.

A cross at the end.

A o--o B Circles at both ends. x--x puts crosses at both. Circles at both ends. x--x puts crosses at both.

Circles at both ends. x--x puts crosses at both.

A -- Yes --> B Text on the line. A -->|Yes| B does the same. Text on the line. A -->|Yes| B does the same.

Text on the line. A -->|Yes| B does the same.

A ~~~ B No line. B is placed after A without one. No line. B is placed after A without one.

No line. B is placed after A without one.

A & B --> C Several links in one line. Several links in one line.

Several links in one line.

Sequence arrows

The arrows between participants in a sequence diagram, written between their names, as in A->>B: Hello.

WriteDraws
->> A solid line with an arrowhead, for a call. A solid line with an arrowhead, for a call.

A solid line with an arrowhead, for a call.

-->> A dashed line with an arrowhead, for a reply. A dashed line with an arrowhead, for a reply.

A dashed line with an arrowhead, for a reply.

-> A solid line without an arrowhead. A solid line without an arrowhead.

A solid line without an arrowhead.

--> A dashed line without an arrowhead. A dashed line without an arrowhead.

A dashed line without an arrowhead.

-) An open arrowhead, for a message sent without waiting. --) is dashed. An open arrowhead, for a message sent without waiting. --) is dashed.

An open arrowhead, for a message sent without waiting. --) is dashed.

-x A cross at the end, for a message that was lost. --x is dashed. A cross at the end, for a message that was lost. --x is dashed.

A cross at the end, for a message that was lost. --x is dashed.

<<->> Arrowheads at both ends. <<-->> is dashed. Arrowheads at both ends. <<-->> is dashed.

Arrowheads at both ends. <<-->> is dashed.

Front matter

A diagram may begin with settings between two --- lines.

  • title: names the diagram.
  • theme, themeVariables and look under config: (or in an %%{init}%% line) are passed over: blackbear always draws in your theme.
  • layout under config: (such as elk or dagre) is passed over too: blackbear lays the diagram out itself.
  • Other settings under config: that change how Mermaid lays a diagram out, such as flowchart.curve, are left out. blackbear lays the diagram out itself.

blackbear's comments

A line that starts with %% is a comment. blackbear reads a few comments of its own, so a diagram keeps working everywhere else.

  • %% bb:title Text names the diagram, and the canvas it is drawn into.
  • %% bb:lanes turns each top-level subgraph of a flowchart into a lane, in the order written.
  • %% bb:rank a=0 b=2 puts nodes in layers, and %% bb:order a=0 b=1 orders them within one.
  • blackbear writes %% bb:namespace and %% bb:canvas when a note's diagram is opened as a canvas. They keep the two connected, so leave them in place.
  • Other renderers read these lines as ordinary Mermaid comments and skip them.

A flowchart in lanes, one for each person:

The flowchart below, drawn in two lanes The flowchart below, drawn in two lanes
%% bb:lanes
flowchart LR
  subgraph you [You]
    ask[Ask for a review]
    merge[Merge]
  end
  subgraph team [Reviewer]
    read[Read it]
    ok{Looks good?}
  end
  ask --> read --> ok
  ok -- Yes --> merge
  ok -- No --> ask

Kinds blackbear doesn't draw

blackbear turns these Mermaid kinds away. The text stays where you wrote it, with a message such as “Blackbear does not draw Gantt charts (gantt)” and the list of kinds it does draw.

KindStarts with
Gantt chartgantt
Pie chartpie
User journeyjourney
Quadrant chartquadrantChart
XY chartxychart
Sankey diagramsankey
Radar chartradar-beta
Treemaptreemap-beta
Venn diagramvenn-beta
Swimlane diagramswimlane-beta
Use case diagramusecase-beta
Tree viewtreeView-beta
Ishikawa diagramishikawa-beta
Wardley mapwardley-beta
Cynefin diagramcynefin-beta
Event modeleventmodeling
Railroad diagramrailroad-ebnf-beta
Agent flowagentflow-beta
ZenUML diagramzenuml
Infoinfo

A diagram can be up to 65,536 characters and 2,000 lines long.