Flowcharts Beyond the Basics with Mermaid

Mermaid flowcharts are perfect when you want diagrams that live next to your code, stay reviewable in git, and can be updated as quickly as your systems change.

This guide skips the “hello world” and focuses on the features that make flowcharts maintainable: subgraphs, reusable styling, clean labels, consistent layout, and patterns you’ll use again and again.

A quick refresher (so the rest makes sense)

Mermaid flowcharts use this basic structure:

• flowchart LR (or TD) sets the layout direction
• A --> B connects nodes
• A[Rectangle], A(Rounded), A{Decision} control shapes
• A -->|label| B adds edge labels

Example

Source

Rendered

1) Layout control that actually improves readability

Pick a direction intentionally

• LR (left-to-right) is great for pipelines and request paths.
• TD (top-down) is great for decision trees and troubleshooting.

Source

Rendered

Use invisible “spacers” to guide layout

Sometimes you need a little structure without adding meaning.

Source

Rendered

Tip: Treat spacers like CSS hacks—use sparingly, but don’t fear them when they improve clarity.

2) Subgraphs (the feature that keeps big diagrams sane)

Subgraphs let you group related nodes. They’re the key to drawing “real” systems without turning your diagram into spaghetti.

Basic subgraph

Source

Rendered

Subgraphs as “swimlanes”

A clean trick is to use subgraphs as swimlanes for responsibility boundaries: client vs platform vs app.

Source

Rendered

3) Node shapes and labels that age well

Use shapes to convey meaning

A few conventions that readers learn quickly:

• Rounded A(Run step) for actions
• Diamond A{Decision?} for branching
• Cylinder A[(DB)] for data stores
• Stadium A([Start]) and B([End]) for boundaries

Multi-line labels

You can use <br/> inside labels to make long text readable.

Source

Rendered

Tip: Prefer short node text + edge labels over giant paragraphs in a single node.

4) Link types: solid, dotted, thick, and “not really a dependency”

Mermaid supports different link styles that you can use to communicate strength or meaning.

• --> normal flow
• -.-> optional / async / “may happen”
• ==> emphasis / strong coupling

Source

Rendered

5) Styling with classDefs (so diagrams look consistent across your blog)

If you only do one “advanced” thing, do this: define a small style palette and reuse it.

A small, reusable style set

Source

Rendered

Apply classes later (cleaner for big diagrams)

When diagrams grow, it’s often clearer to define nodes first, then apply classes.

Source

Rendered

6) Label edges like you mean it

Edge labels are how you keep nodes short while still conveying meaning.

Source

Rendered

Tip: If every edge label is “calls”, remove edge labels entirely. Label only what differentiates the link.

7) Clickable diagrams (turn a diagram into navigation)

If your renderer supports it, Mermaid can attach links to nodes.

Source

Rendered

Replace the example URLs with your own internal documentation links.

8) A real “beyond basics” example: deploy + drain done cleanly

This example combines subgraphs, edge labels, link types, and a small style palette.

Source

Rendered

9) A checklist for “blog-ready” flowcharts

Before you publish:

• Can a reader understand it in 10 seconds? If not, split it into two diagrams.
• Are your labels consistent? (Requests, events, retries, timeouts)
• Do subgraphs reflect responsibility boundaries? (Client / platform / service)
• Are you using shapes intentionally? (decisions vs actions vs data)
• Are edge labels doing real work? Label the why, not the obvious.
• Do you have a stable style palette? Reuse classDef names across posts.

Where to go next

If you found subgraphs and class-based styling useful, the next Mermaid feature to learn is sequence diagrams—they’re often the best way to explain time (retries, backoffs, and latency) without contorting a flowchart.