Mermaid Markdown Guide: Add Diagrams to README Files and Docs

# Mermaid Markdown Guide: Add Diagrams to README Files and Docs

Mermaid Markdown lets you put diagrams directly inside documentation with a fenced code block. Instead of exporting an image from a drawing tool, you write a small text diagram, commit it with the doc, and let the Markdown renderer turn it into a flowchart, sequence diagram, class diagram, ER diagram, timeline, or architecture sketch.

This is useful for README files, pull requests, internal docs, product specs, runbooks, and developer onboarding pages because the diagram changes in the same diff as the explanation.

Basic Mermaid Markdown Syntax

Most Mermaid-enabled Markdown tools use a fenced code block with `mermaid as the language:

flowchart TD

Start[Open the docs] --> Edit[Edit Markdown]

Edit --> Preview[Preview Mermaid diagram]

Preview --> Commit[Commit the change]

When rendered, the inner block becomes a diagram. When a platform does not support Mermaid, readers will still see the source text, which is usually better than a broken image.

Markdown Flowchart Example

Use a flowchart when your documentation explains a process, decision tree, support workflow, or deployment path.

flowchart TD
    Issue[User reports issue] --> Triage[Check logs and reproduce]
    Triage --> Bug{Confirmed bug?}
    Bug -->|No| Reply[Explain expected behavior]
    Bug -->|Yes| Fix[Create fix branch]
    Fix --> Test[Run tests]
    Test --> PR[Open pull request]
    PR --> Release[Ship release]

Keep node labels short. Put long explanations in the Markdown around the diagram, not inside every box.

Mermaid Sequence Diagram in Markdown

Sequence diagrams are good for API docs because they show who calls whom and in what order.

sequenceDiagram
    participant Browser
    participant App
    participant API
    participant DB

    Browser->>App: Submit login form
    App->>API: POST /sessions
    API->>DB: Find user and verify password
    DB-->>API: User record
    API-->>App: Session token
    App-->>Browser: Redirect to dashboard

This style is especially helpful in pull requests because reviewers can compare the intended interaction with the code change.

README Architecture Diagram Example

A small architecture diagram near the top of a README can explain a project faster than paragraphs of setup notes.

flowchart LR
    subgraph Client
        Web[Next.js app]
        CLI[Developer CLI]
    end

    subgraph Backend
        API[REST API]
        Worker[Background worker]
    end

    subgraph Storage
        Postgres[(Postgres)]
        Queue[Job queue]
    end

    Web --> API
    CLI --> API
    API --> Postgres
    API --> Queue
    Queue --> Worker
    Worker --> Postgres

For README files, show the major parts only. Detailed infrastructure belongs in a separate architecture document.

Markdown Table plus Mermaid Diagram

Mermaid works best when it is paired with plain Markdown context. For example, explain responsibilities in a table, then show the flow below it.

flowchart LR
    WebApp[Web app] --> API[API]
    API --> Queue[Queue]
    Queue --> Worker[Worker]
    Worker --> Done[Job complete]

This keeps the diagram readable while still giving readers the detail they need.

Tips for Mermaid in Markdown

1. Use `mermaid fences, not screenshots, when the platform supports Mermaid.
2. Add one sentence before the diagram that tells readers what question it answers.
3. Keep diagrams focused on one workflow or system boundary.
4. Prefer stable labels over implementation details that change every week.
5. Preview before committing because different Markdown renderers may support different Mermaid versions.
6. If a diagram is large, split it into multiple smaller diagrams instead of forcing one giant canvas.

Where Mermaid Markdown Works

Mermaid is commonly supported in developer documentation platforms such as GitHub Markdown, GitLab Markdown, many static site generators, and several engineering wikis. Support varies by renderer, so advanced syntax may work in one place and fail in another.

If you are writing for a mixed audience, start with flowcharts and sequence diagrams. They are widely understood and easy to maintain in text.

Common Markdown Mermaid Mistakes

The most common mistake is wrapping Mermaid source in a generic code block instead of a Mermaid code block. Use this:

flowchart LR

A --> B

Not this:

flowchart LR

A --> B

Another common issue is putting too much prose inside node labels. A Mermaid diagram should guide the reader. The surrounding Markdown should explain the details.

Final Recommendation

Use Mermaid Markdown when the diagram belongs with the documentation and needs to change over time. Start with a small flowchart or sequence diagram, preview it, and commit the Mermaid source next to the Markdown it explains.

You can draft the diagram in MermaidEditor.lol first, then paste the final Mermaid block into your README, docs page, or pull request.