If you've ever opened a codebase and struggled to understand how different modules connect, you already know the problem. Documentation without visuals is hard to follow, and hand-drawn diagrams get outdated fast. Mermaid diagram code examples for software documentation solve this by letting you write diagrams as plain text that lives right alongside your code. When the code changes, you update a few lines of text instead of redrawing a box-and-arrow chart from scratch.

What exactly is Mermaid, and why do developers use it for documentation?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from a simple text-based syntax. Instead of dragging shapes around in a drawing app, you write short code blocks that describe relationships, flows, and sequences. A Markdown-compatible renderer then turns that code into a clean SVG or image.

Developers reach for Mermaid because it fits naturally into existing workflows. It works inside Markdown files, GitHub READMEs, GitLab wikis, Notion pages, Confluence, and many static site generators. You don't need a separate design tool or a designer on call. If you can write a comment in code, you can write a Mermaid diagram.

For software documentation specifically, this matters because diagrams need to stay current. A flowchart that describes your authentication system should change when your auth logic changes. With Mermaid, that diagram is a code block sitting in the same pull request as the feature code. Reviewers see both at once.

What types of diagrams can you create with Mermaid code?

Mermaid supports several diagram types that are directly useful in software documentation:

  • Flowcharts for decision logic, user flows, and process steps
  • Sequence diagrams for API call flows, request/response cycles, and message passing between services
  • Class diagrams for object-oriented architecture and data models
  • State diagrams for finite state machines and lifecycle transitions
  • Entity-relationship diagrams for database schema design
  • Gantt charts for project timelines in technical planning docs
  • Pie charts for simple data breakdowns in reports

If you're new to the syntax, the Mermaid syntax cheatsheet covers the basics of each diagram type in one place.

What does a flowchart code example look like?

Flowcharts are the most common starting point. Here's a simple example that shows a login process:

flowchart TD
  A[User opens app] --> B{Has valid token?}
  B -->|Yes| C[Show dashboard]
  B -->|No| D[Show login form]
  D --> E[User submits credentials]
  E --> F{Credentials valid?}
  F -->|Yes| G[Generate token]
  G --> C
  F -->|No| H[Show error message]
  H --> D

The flowchart TD line sets the direction (top-down). Each node has an ID and a label in brackets. Arrows connect them, and conditions go in pipes. This renders a clean, readable flowchart that any team member can edit without design skills.

For more detailed flowchart examples and syntax breakdowns, see how to create flowcharts using Mermaid code.

How do you write a sequence diagram for API documentation?

Sequence diagrams show interactions between components over time. They're especially useful for documenting API request lifecycles. Here's an example of a typical REST API call:

sequenceDiagram
  participant Client
  participant Gateway
  participant AuthService
  participant Database
  Client->>Gateway: POST /api/login
  Gateway->>AuthService: Validate credentials
  AuthService->>Database: Query user record
  Database-->>AuthService: User data
  AuthService-->>Gateway: JWT token
  Gateway-->>Client: 200 OK + token

The arrows tell the story. Solid arrows (->>) mean requests; dashed arrows (-->>)) mean responses. The participants are declared at the top so the diagram knows who's involved.

This kind of diagram sits well in an API reference page or a developer onboarding guide. It answers "what happens when I call this endpoint?" in a way that paragraphs of text can't match.

How do you document a database schema with a class diagram?

Mermaid's class diagram syntax works well for showing data models and their relationships, even when you're not strictly doing object-oriented programming:

classDiagram
  class User {
    +int id
    +string email
    +string passwordHash
    +datetime createdAt
    +login() bool
  }
  class Post {
    +int id
    +string title
    +string body
    +datetime publishedAt
    +publish() void
  }
  User "1" --> "" Post : writes

The "1" --> "" notation shows a one-to-many relationship. This gives readers a quick mental model of the data structure without reading migration files or ORM definitions.

When should you use a state diagram in your docs?

State diagrams are the right choice when a system or entity goes through defined stages. Order processing, user account status, CI/CD pipeline stages these all have clear states and transitions:

stateDiagram-v2
  [] --> Pending
  Pending --> Processing : payment received
  Processing --> Shipped : items packed
  Shipped --> Delivered : confirmed
  Pending --> Cancelled : user cancels
  Processing --> Cancelled : timeout
  Delivered --> []
  Cancelled --> []

Each arrow represents a transition with an optional label explaining what triggers the change. This is far clearer than a table of statuses in a README.

What are the most common mistakes when writing Mermaid code for documentation?

Several issues come up repeatedly when developers add Mermaid diagrams to their docs:

  • Overloading a single diagram. A flowchart with 40 nodes is unreadable. Break it into smaller diagrams, each showing one piece of the system.
  • Using special characters in labels without quoting them. Parentheses, quotation marks, and brackets inside labels can break parsing. Wrap labels in double quotes when in doubt.
  • Forgetting that diagram direction affects layout. TD (top-down) versus LR (left-right) changes how the diagram looks dramatically. Pick the direction that matches the information flow.
  • Not testing diagrams before merging. A broken Mermaid block in a README shows up as raw text. Always preview your diagrams in a tool like the Mermaid Live Editor before committing.
  • Mixing diagram types in one code block. Each mermaid block supports exactly one diagram type. If you need a flowchart and a sequence diagram, use two separate blocks.

How do you make Mermaid diagrams readable on different screen sizes?

A few practical adjustments help your diagrams hold up across devices:

  1. Keep node labels short. "Validate JWT" is better than "Validate the JSON Web Token against the signing key."
  2. Use LR direction for wide layouts and TD for narrow ones. If your docs are viewed mostly on desktop monitors, LR often gives more horizontal space.
  3. Add %% comments in your Mermaid code to explain non-obvious connections. These don't render but help future contributors understand intent.
  4. Limit each diagram to one clear message. If you need to explain two separate flows, write two diagrams.

The full Mermaid syntax reference covers additional styling options like themes, node shapes, and subgraph grouping that help with readability.

Where should Mermaid diagrams live in your project?

The most common placements are:

  • README files high-level architecture overviews and quick-start flows
  • Architecture Decision Records (ADRs) diagrams that justify a design choice
  • Wiki pages or docs sites detailed system diagrams, API flows, and data models
  • Pull request descriptions temporary diagrams that explain a change during review
  • Inline code comments rare but useful for complex algorithm visualization

The key rule is proximity. Put the diagram near the code or documentation it describes. A diagram buried in a separate design doc that nobody updates is worse than no diagram at all.

Quick checklist for adding Mermaid diagrams to your software docs

  • Pick the right diagram type for the information you're showing (flowchart for process, sequence for interactions, class for data models, state for lifecycles)
  • Write the diagram code in a plain text block and preview it before committing
  • Keep labels concise and quote special characters
  • Choose a layout direction (TD or LR) that fits the content and viewport
  • Place the diagram in the same file as the documentation it supports
  • Review and update diagrams in the same pull requests that change related code
  • Break large diagrams into smaller, focused ones
  • Add comments (%%) for anything non-obvious so future editors understand the intent

Start by adding one diagram to a page you maintain today even a simple three-node flowchart. Once you see how little effort it takes compared to maintaining a separate drawing tool file, it becomes a habit fast.