Guides
Mermaid flowcharts: diagrams as code
Mermaid is an open-source tool that draws diagrams from plain text. A flowchart is written as a few lines such as "A --> B", stored next to your documentation or code, and rendered automatically by tools like GitHub, GitLab, Notion and Obsidian.
What Mermaid is
Mermaid is a JavaScript library, first released in 2014, that turns a text description into a diagram. It supports flowcharts, sequence diagrams, state diagrams, Gantt charts and more. A minimal flowchart looks like this:
flowchart TD
A([Order received]) --> B[Check stock]
B --> C{In stock?}
C -->|Yes| D[Ship order]
C -->|No| E[Notify customer]The renderer takes care of shapes, positions and arrows. You only describe the structure.
Why teams write diagrams as code
- Versioning: the diagram is text, so changes show up in diffs and code reviews.
- No binary files: nothing to re-export when the process changes; edit a line instead.
- Lives with the documentation: in a README, a wiki page or an architecture decision record.
- Rendered where people already work, without plugins on many platforms.
The trade-off is control: layout is automatic, so you cannot place a box exactly where you want. For most documentation that is an advantage, not a limitation.
Where Mermaid renders
GitHub and GitLab render Mermaid code blocks in Markdown files, issues and merge or pull requests; see Mermaid on GitHub and GitLab. Notion and Obsidian have native support too, and many documentation generators offer plugins; see Mermaid in Notion, Obsidian and docs tools.
Mermaid compared with drawing tools
Drawing tools such as whiteboards or diagram editors are better for free-form sketches, architecture posters and anything where position carries meaning. Mermaid is better for diagrams that follow a structure (steps, decisions, owners), that several people maintain, and that must stay in sync with text. A useful rule: if the diagram will be updated more than once, and its layout does not need to be pixel-perfect, write it as code.
What a team needs to get started
Very little. Agree on a direction (top-down or left-to-right), a naming convention for node ids, and where diagrams live (README, wiki, docs folder). Then treat diagrams like code: changes go through review, and outdated diagrams are fixed or deleted rather than left to mislead readers.
Learning the syntax
Flowcharts need only a few constructs: a direction, nodes with shapes, arrows with optional labels. The Mermaid flowchart syntax cheat sheet covers them, and subgraphs and styling explains how to group steps by owner and highlight parts of a chart.
From a description to Mermaid
Writing Mermaid by hand is quick for small charts and tedious for large ones. Another route is to describe the process in plain language, let an AI flowchart generator build the chart, and export it as Mermaid. Flowchartio exports a flowchart TD file where each owner becomes a subgraph, ready to paste into a README.
Mermaid or an image?
Mermaid suits documentation that changes and lives in text-based tools. Slides, PDFs and emails still need images. The comparison of PNG, SVG and Mermaid exports helps choose.
For software documentation in general, including API workflows, see flowcharts for APIs and software.
In this guide
Each article goes deeper into one part of the topic.
- Mermaid flowchart syntax cheat sheetA Mermaid flowchart starts with "flowchart" and a direction (TD, LR…), then declares nodes with an id and a shape, such as A[Step] or B{Question?}, and connects them with arrows like A --> B or B -->|Yes| C.
- Mermaid diagrams in GitHub and GitLabIn GitHub and GitLab, put the diagram in a fenced code block whose language is "mermaid". The platform renders it as a diagram in Markdown files, issues, pull or merge requests and wikis, with no image to upload.
- PNG, SVG or Mermaid: which flowchart format to exportExport PNG when the chart goes into slides, emails or tools that only accept images; SVG when it must stay sharp at any size or be edited in a design tool; Mermaid when it lives in a wiki or repository and will change over time.
- Mermaid in Notion, Obsidian and documentation toolsNotion and Obsidian render Mermaid natively from a code block set to Mermaid. Documentation generators such as Docusaurus and MkDocs support it through an official plugin or extension, while Confluence generally needs a marketplace app.
- Mermaid subgraphs and stylingUse "subgraph id [Title] … end" to group nodes, for example one group per team to imitate swimlanes. Use classDef and class (or the ::: shorthand) to style groups of nodes, and style for a single node.
Turn your process into a flowchart
Describe it in a few sentences. Flowchartio draws the flowchart, then you refine it in conversation.
Generate a flowchart