Mermaid documentation, as a practical map of the official docs

The mermaid documentation is easier to use when you treat the official pages as the spec and this page as a map. The file starts with a diagram keyword, the syntax pages are split by diagram type, and an error usually names the line that broke.

I still lose people in those official pages, including myself on a tired afternoon. The pages are accurate. They are also dense, and they assume you already know which diagram you meant. This is the route I wish someone had handed me: what a file is, where the flowchart, sequence, class, ER, and Gantt material lives in spirit, and how to read an error without guessing. It does not replace the spec. If the spec and this page disagree, believe the spec, then check the version you're rendering with.

If you want the definition before the map, what Mermaid is is the short orientation. The one-page cheat sheet is the reminder you keep open while you type. Neither of those is the official manual. They're how I stop re-reading the manual for a colon I already knew.

The official pages stay the spec

The official Mermaid documentation is the language. I'm not going to paste it here and pretend this is a mirror. A mirror goes stale the week a keyword changes, and then you have two specs, which is worse than one dense spec.

What I will do is tell you how I use those pages. I open them when I need a form I don't remember, like the exact cardinality pair on an ER line or the way a Gantt date is written. I don't open them to remember that the first line is the diagram type. That's stable, and it's the thing people skip because they're hunting for a shape.

I also don't treat a blog, a cheat sheet, or a rendered sample as a higher authority than the syntax page for that type. Samples omit the case you're about to hit. The page has the case, buried under three examples that aren't yours. Search the page for the token you typed. If the token isn't there, you invented it. I have invented useCaseDiagram. It is not a keyword. The renderer was correct to reject it.

When a teammate says "the docs say this works" and the preview doesn't, ask which page and which version. "The docs" is a pile of pages across years of the library. I'm not going to claim a feature list for the hosted docs site. Open the page, quote the example, and compare it to the file. That's the whole method.

A file starts with one keyword

A diagram file is not a document with a header. The first real line is the keyword: flowchart, sequenceDiagram, classDiagram, erDiagram, gantt, and the rest. Blank lines don't count. A comment doesn't count as the keyword either, but comments are allowed, and they use %%.

%% refund policy, auto-approve under the limit
flowchart TD

That comment is for the next editor, not for the reader of the picture. The picture starts at flowchart. If you put a title sentence above the keyword, inside the Mermaid file, the parser tries to read your sentence as a diagram type. It fails on line 1, and the message looks like the tool is broken. Move the sentence into the markdown above the fence.

Direction, when the type has one, sits on that same first line or on the next. flowchart TD is top to bottom. flowchart LR is left to right. I pick it before I draw nodes, because changing it later reflows every arrow and the review diff looks like I redesigned the policy. I didn't. I turned the page sideways.

Ids and labels split on that first real content line after the keyword. pay[Send refund] means the id is pay and the label is "Send refund". The official flowchart page will show you more shapes than you need. You need this split. The id is what arrows point at. The label is what a human reads. If you use the label as the id, every rename breaks the arrows, and the diff is noise.

The format notes go further on how a fence sits in a markdown file. The syntax rules that travel between types are the closer read once the keyword is in place and you're still getting parse errors. This page is the map. Those are the streets.

How those syntax pages are shaped

I think of the official material as a set of type pages plus a pile of configuration. The type page answers "what can this diagram say." Configuration answers "what colors and spacing look like." I almost never need configuration while I'm trying to make a sentence true. I need it when someone asks for the company blue, and even then I do it last.

In spirit, the pages line up like this:

• Flowchart pages are nodes, arrows, subgraphs, and direction.
• Sequence pages are participants, messages, and blocks such as alt and loop.
• Class pages are types, members, and the lines that mean inheritance or association.
• ER pages are entities, keys, and cardinality.
• Gantt pages are tasks, dates, and sections. A Gantt line wants dateFormat YYYY-MM-DD before the tasks, or the dates are just words.

There is more. State, mind map, journey, git, pie, architecture. The diagram index is where I send someone who doesn't know the type name yet. Don't start on a configuration page. You'll style a diagram you haven't written.

Each type page tends to lead with a tiny example, then a table of symbols, then the cases that don't fit the tiny example. Read the tiny example until you can type it from memory. Then use the table. If you start in the table, you'll combine tokens from two rows that were never meant to sit on one line. That's how I wrote a sequence arrow with a flowchart label on it and spent ten minutes blaming the preview.

The examples on those pages are minimal on purpose. They're not your domain. Copy the shape, replace the nouns, and delete the sample's extra decoration. A sample that shows every style class is a style demo. Your policy doc doesn't need five colors to say yes and no.

Flowcharts, once you know which page you opened

A flowchart page is about a path. Something starts, a question splits the path, and the paths join or stop. The flowchart syntax page on this site is our short version of that material, with the shapes I actually use. The official page is still the spec when a shape isn't listed.

Here's a file that matches the way that page is organized. Keyword, direction, then a question, then labeled arrows.

flowchart TD
    ask[Refund request] --> gate{Over the auto limit?}
    gate -->|No| auto[Approve and pay]
    gate -->|Yes| human[Ask a reviewer]
    human -->|Approved| auto
    human -->|Rejected| note[Send the reason]

The diamond is the only decision. The arrow labels are the answers. Without |No| and |Yes|, the diamond is a fork and the reader invents the policy. I have watched that happen in a support review. Two people agreed the picture was "clear" and disagreed about which branch was the automatic one.

Subgraphs belong on this page too, in spirit. They group nodes. They don't change the logic. If you can't name the group in two words, you have two flowcharts. The official page will show you styling after the structure. I stop before styling unless a color carries a meaning I'll explain in one sentence under the figure.

A mistake I make when I "follow the docs" too literally is copying a sample's node id A and B into a real policy and then extending it for months. A doesn't survive contact with a second author. Rename to ask and gate while the file is still small. The docs use short letters because the sample is about syntax. Your file is about a refund.

Sequences, and the cast you declare first

A sequence page is about a conversation. The sequence diagram page starts from participants and arrows, which is the right order. The official page does the same job with more message types than a normal design doc needs. Solid request, dotted reply, and alt will carry you until they don't.

sequenceDiagram
    autonumber
    participant App as App
    participant Mail as Mail
    participant User as User
    App->>Mail: Send reset link
    Mail-->>User: Link
    User->>App: Open the link
    alt token valid
        App-->>User: Choose a new password
    else token expired
        App-->>User: Ask for a new link
    end

Declare participants before the first message, in the left-to-right order you want. The first time a name appears is the order many renders keep. If Mail shows up late, it lands on the right and the eye reads the story backwards. I declare the cast even when the sample in the docs gets away with skipping it. Samples are short. Yours won't stay short.

The colon after the arrow is not decoration. App->>Mail Send reset link is a broken line. App->>Mail: Send reset link is a message. The docs show the colon in the happy example, and people still drop it when they type fast. I drop it when I type fast. The preview is the correction.

end closes alt. It is not a participant and not a message. The docs use end because the block has to finish. If you name a participant End, you will have a bad afternoon. Call them App, Mail, and User.

autonumber is optional. I turn it on when a review will refer to steps. I leave it off when the diagram is three messages and a number would look like a specification we don't have. The docs will show both. Pick one and don't also type "1." into the message text.

Class, ER, and Gantt answer different questions

These three get lumped together as "the structured ones." They aren't the same page, and they aren't the same question.

A class diagram is types in code. Members, inheritance, composition. If you're arguing about a method, you're on the class page. If you're arguing about a foreign key, you're in the wrong file.

An ER diagram is rows. Entities, key marks, and a cardinality line with a verb after a colon. The line CUSTOMER ||--o{ ORDER : places is the whole point of that page. The double bar is "exactly one." The circle and crow are "zero or more." The verb is required. I keep the official cardinality table bookmarked and I still say the sentence out loud, because the parser accepts a reversed foot.

A Gantt chart is a schedule. Tasks have dates. dateFormat YYYY-MM-DD belongs near the top, then a section, then a task with a start and a duration. I don't use a Gantt to show a decision. There is no diamond hiding in a date range. If the question is "what happens if the review slips," that's a flowchart, and the Gantt can show the slipped date after you decide.

I open one page at a time. A class example pasted under an erDiagram keyword fails, and the error looks like a missing brace when the real problem is that you changed questions in the middle of the file. One file, one keyword. A second question gets a second fence, with a sentence between them that says why both pictures exist.

The diagram examples are where I send someone who learns better from a finished picture than from a table. Use them after you know which page you're on. An example gallery will not tell you that your keyword is wrong. It will show you a pretty neighbor.

Read the error like a compiler message

The preview's error is trying to be a compiler. It names a line more often than people admit. Go to the line. Read the token it quotes. Compare that token to the page for the diagram type you think you opened.

The guide to syntax errors is the list I keep for the failures that repeat. My own reading habit is shorter:

1. Check the first real line. Is it a keyword this renderer knows?
2. Check the line number in the message, not the line I was editing. A missing end often reports later.
3. Check quotes around any label with parentheses, a colon, or a question mark that isn't a diamond.
4. Check that end is a closer, not an id. The last step can be done or stop.
5. If the message is a shrug, delete from the bottom until it renders, then add one line back.

Don't fix styling while the parse is red. Color will not make a missing colon legal. I have "fixed" a theme, rebuilt, and still had the same error, because the theme was never the input that failed. The line was.

A worked miss from last quarter. The error said it expected a different token on the relationship line. I had written CUSTOMER ||--o{ ORDER places because the sample's colon looked optional when I squinted. It isn't optional. CUSTOMER ||--o{ ORDER : places is the line. The page shows the colon. I skipped it because I was copying the symbols and improvising the verb. Improvising is fine. Skipping the character the sample actually depends on is not.

When the docs and the error disagree, I check whether I pasted from an old bookmark. Mermaid has added diagram types. It has not, in my experience, started accepting a flowchart node named end just because a blog said you could try it. If you're unsure which version a tool is running, say so and try the smallest example from the current type page. If the smallest example fails, you're not in the language you think you're in. If it passes, your file diverged from it, and the divergence is the bug.

A schema you can check against the ER page

This is the file I use to test whether I still remember the ER page without opening it. One customer, many orders, each order at least one line item. Keys marked. Verbs after colons.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains
    CUSTOMER {
        string id PK
        string email
    }
    ORDER {
        string id PK
        string customerId FK
        string status
    }
    ITEM {
        string id PK
        string orderId FK
        int qty
    }

Read it the way the page wants you to read it. The bar is on CUSTOMER, so an order has one customer. The crow is on ORDER, with a circle, so a customer may have no orders yet. That's a new account, and it's more honest than a mandatory many. customerId is the foreign key on the order, the many side. Putting it on the customer would say the person row stores one order id, and the foot would be lying.

ORDER ||--|{ ITEM : contains says an order has one or more items. I use that only when an empty order can't exist in this product. If a draft order has no items yet, the honest foot is o{, zero or more, and I should not copy this sample blindly. The docs will show you both pairs. The product decides which pair is true.

I don't list every column. The page allows a long attribute block. A long block turns the relationship into a footnote. Keys, plus the column that makes the link make sense, are enough. The rest belongs in the migration, which is already the spec for columns.

If this fails to render, the colon is the first thing I check, then a comma I accidentally left in an attribute line, then an entity name with a space. LINE ITEM is two tokens. ITEM is a name. The label the reader sees can be discussed in the prose. The entity id has to be a single token in this style.

What I keep next to the bookmark

I keep three things, and I try not to keep a fourth copy of the manual.

The official type page for whatever I'm editing that day. The cheat sheet, so I don't reopen the type page for a diamond or a dotted arrow. And the diagram in git, next to the code it describes, so the page and the file can be compared in a pull request.

I don't keep a personal wiki that restates the cardinality table. It drifts. When I forget a symbol I look it up again. That takes a minute. Shipping a wrong foot because my notes were confident takes a week to unwind, usually after someone has built the migration.

What a Mermaid diagram is is the page I send to someone who has never seen the keyword. I don't send them the official configuration reference. Configuration is how the picture is painted. They need to know the picture is text.

When the official page and a rendered sample disagree about a detail, I reproduce the official sample in the smallest fence I can, in the same renderer the repo uses. If that sample fails, the renderer is behind the page, and I write the diagram in the older form. If the sample passes, my diagram is the thing that's wrong. I don't "fix" a passing sample to match a habit.

Open the editor and paste the smallest official example for the type you think you're writing. If that renders, your file is the delta. If it doesn't, you're not looking at the language you think the docs are describing, and no amount of rearranging boxes will help.