mermaid markdown diagrams flowchart documentation

Mermaid in Markdown: Create Flowcharts, Sequence Diagrams, and More

Learn Mermaid syntax for Markdown with copy-ready flowchart, sequence, class, Gantt, mind map, and ER diagram examples, plus preview, export, compatibility, and accessibility guidance.

W
WordToMD Team
·

Technical diagrams often become stale because editing them requires finding the original design file, opening a separate application, and exporting another image. Mermaid takes a different approach: the diagram is defined as text and stored beside the documentation.

To add Mermaid to Markdown, place the diagram definition inside a fenced code block with the mermaid language identifier. Use the Mermaid Diagram Preview to render the syntax locally, correct errors, copy the complete Markdown fence, or download an SVG.

This guide starts with a small flowchart and builds toward sequence, class, Gantt, mind map, and entity-relationship diagrams.

Mermaid in 30 Seconds

A basic Mermaid block looks like this:

```mermaid
flowchart LR
  Draft --> Review
  Review --> Publish
```

The opening fence tells a compatible renderer that the content is Mermaid syntax. flowchart LR selects a flowchart arranged from left to right. The remaining lines define nodes and connections.

If the destination does not support Mermaid, readers will usually see a code block instead of a diagram. That fallback preserves the source, but it is not a replacement for checking compatibility before publication.

Why Use Text-Based Diagrams?

Mermaid is especially useful when a diagram:

  • belongs to version-controlled documentation;
  • changes along with code or procedures;
  • needs meaningful pull-request diffs;
  • uses standard shapes and relationships;
  • should be editable without a proprietary design file;
  • must be regenerated in light and dark themes.

It is less suitable for detailed illustration, pixel-perfect layout, freehand annotation, or visual design requiring precise manual placement. In those cases, use a drawing tool and export an accessible SVG or image.

Example 1: A Flowchart

Flowcharts describe a process, decision, or routing rule.

```mermaid
flowchart TD
  A[Choose a DOCX file] --> B{File valid?}
  B -->|Yes| C[Convert to Markdown]
  B -->|No| D[Show an error]
  C --> E[Review the output]
  E --> F[Copy or download]
```

Key syntax:

  • TD means top to bottom.
  • LR means left to right.
  • [Text] creates a rectangular process node.
  • {Text} creates a decision node.
  • --> creates a directional connection.
  • -->|Label| adds text to a connection.

Use stable, short node IDs such as A or validate. Keep the visible label inside brackets so changing the wording does not require changing every connection.

Add a subgraph

Subgraphs group related steps:

```mermaid
flowchart LR
  subgraph Browser
    Upload[Choose file] --> Convert[Convert locally]
  end

  subgraph Output
    Preview[Preview Markdown] --> Save[Download file]
  end

  Convert --> Preview
```

Use subgraphs when the grouping communicates ownership, system boundaries, or phases. Do not add a box merely for decoration.

Example 2: A Sequence Diagram

Sequence diagrams show interactions in time order. They work well for API calls, authentication, browser workflows, and event-driven systems.

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant Converter

  User->>Browser: Select DOCX file
  Browser->>Converter: Pass local file data
  Converter-->>Browser: Return Markdown
  Browser-->>User: Show editable preview
```

Common arrows:

  • ->> sends a solid message.
  • -->> sends a dashed response.
  • participant declares a system or service.
  • actor declares a human or external role.
  • autonumber labels interactions in order.

Focus on one scenario. A sequence diagram that attempts to show every alternative and every internal function becomes harder to understand than the code.

Show an alternative path

```mermaid
sequenceDiagram
  participant Client
  participant API

  Client->>API: POST /documents
  alt Valid request
    API-->>Client: 201 Created
  else Invalid request
    API-->>Client: 400 Bad Request
  end
```

Use alt, else, and end for meaningful branches. If the branch requires several pages of explanation, link to prose below the diagram.

Example 3: A Class Diagram

Class diagrams describe types, properties, operations, inheritance, and relationships.

```mermaid
classDiagram
  class Document {
    +String name
    +String content
    +convert()
  }

  class MarkdownDocument {
    +String frontmatter
    +render()
  }

  Document <|-- MarkdownDocument
```

This example states that MarkdownDocument inherits from Document. Use class diagrams for a conceptual model, not as an automatic replacement for complete API reference documentation.

Good class diagrams omit details that do not help the reader understand the design. Showing every private field can turn the diagram into a less searchable version of the source code.

Example 4: A Gantt Chart

Gantt charts show tasks across time. They are useful for release plans, migrations, and documentation projects.

```mermaid
gantt
  title Documentation migration
  dateFormat YYYY-MM-DD

  section Preparation
  Inventory content :done, inventory, 2026-11-03, 3d
  Define templates  :done, templates, after inventory, 2d

  section Migration
  Convert documents :active, convert, 2026-11-08, 7d
  Editorial review  :review, after convert, 5d

  section Publish
  Final validation  :validate, after review, 2d
```

Keep dates explicit and use task IDs when one task depends on another. Remember that a diagram stored in documentation will not update itself when the real project schedule changes. Assign ownership for keeping it current.

Example 5: A Mind Map

Mind maps organize ideas around a central topic.

```mermaid
mindmap
  root((Markdown quality))
    Structure
      Headings
      Lists
      Tables
    Accessibility
      Alt text
      Link text
      Reading order
    Publishing
      GitHub
      Obsidian
      Documentation site
```

Mind maps are most effective during planning or as a high-level overview. They are less useful for precise relationships because the tree structure can imply hierarchy where the real concepts overlap.

Example 6: An Entity-Relationship Diagram

ER diagrams describe data entities and their relationships.

```mermaid
erDiagram
  AUTHOR ||--o{ DOCUMENT : writes
  DOCUMENT ||--o{ REVISION : contains
  DOCUMENT }o--o{ TAG : uses

  AUTHOR {
    string id
    string name
  }

  DOCUMENT {
    string id
    string title
    datetime published_at
  }
```

Use an ER diagram to explain the model and a schema or migration file to define the implementation. A diagram may omit indexes, constraints, and fields that are not relevant to the current explanation.

Preview Mermaid Before Publishing

Writing diagrams directly in a long Markdown document makes syntax errors difficult to isolate. A focused preview loop is faster:

  1. Open the Mermaid Diagram Preview.
  2. Paste only the diagram definition, without the outer code fence.
  3. Render the diagram.
  4. Read any syntax error and correct the referenced area.
  5. Copy the generated fenced Markdown.
  6. Download the SVG when the destination needs a static asset.
  7. Test the final Markdown in its real platform.

The preview renders in your browser with a strict security configuration. Diagram callbacks and other interactive behaviors may be disabled even if another Mermaid installation permits them. That conservative behavior is appropriate for a general preview tool.

Common Mermaid Errors

The diagram type is missing

Incorrect:

A --> B

Correct:

flowchart LR
  A --> B

The first line identifies the diagram grammar.

Punctuation in a label breaks parsing

Quote complex labels:

flowchart LR
  A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]

This is particularly useful for parentheses, punctuation, and labels that resemble syntax.

A reserved word is used unexpectedly

Mermaid grammars have keywords. The official flowchart documentation specifically warns that lowercase end can break a flowchart. Capitalize it or place the visible text inside a quoted node label:

flowchart LR
  Start --> Finish["End"]

The code fence is incorrect

The language identifier belongs immediately after the opening backticks:

```mermaid
flowchart LR
  A --> B
```

Do not indent the complete fence unless the surrounding Markdown syntax requires it.

It works in one platform but not another

Mermaid evolves, and platforms can use different renderers, versions, security settings, and enabled diagram types. A syntax feature supported by the newest Mermaid release may fail in a platform using another implementation or older version.

Prefer widely supported syntax for documents that move between platforms. Test advanced shapes, themes, directives, and newer diagram types in every required destination.

Platform Compatibility

Compatibility should be tested rather than assumed:

PlatformCurrent documented approachImportant note
GitHubUse a fenced mermaid blockGitHub documents rendering in Markdown files, issues, discussions, pull requests, and wikis
GitLabUse a Mermaid code block in GitLab Flavored MarkdownGitLab documents its supported Mermaid version; self-managed installations may differ
ObsidianUse a fenced mermaid block in a noteObsidian’s renderer and supported features can change between releases
Material for MkDocsConfigure a Mermaid custom fenceNative theme integration requires documented pymdownx.superfences configuration
Generic Markdown parserOften displays code onlyMermaid rendering usually requires a JavaScript integration or build plugin

Check the current official documentation before relying on a newer feature:

For a documentation site you control, pin the Mermaid dependency version and test upgrades. Otherwise, a minor syntax change can alter diagrams across the entire site.

Mermaid and Accessibility

A rendered SVG does not automatically communicate its meaning to every reader. Treat the diagram as a visual summary and provide an equivalent explanation in nearby prose.

For the earlier conversion flowchart, add text such as:

The user selects a DOCX file. Valid files are converted locally and displayed for review; invalid files produce an error. The user can then copy or download the reviewed Markdown.

Accessibility practices:

  • introduce what the diagram explains;
  • summarize the conclusion after complex diagrams;
  • do not encode meaning with color alone;
  • use readable labels rather than internal abbreviations;
  • maintain sufficient contrast in light and dark themes;
  • avoid diagrams that require precise mouse interaction;
  • provide a text or table alternative for essential information;
  • export SVG with care when the static file must carry an accessible name.

The source code is useful to authors, but it is not necessarily a good text alternative for readers.

Designing Diagrams That Stay Readable

Keep one purpose per diagram

A diagram should answer a question such as “What happens after a failed request?” or “Which service owns each data store?” If it attempts to explain the entire system, split it.

Prefer short labels

Put detailed explanations in prose. Long labels force narrow nodes, awkward line wrapping, and large diagrams on mobile screens.

Use direction intentionally

Left-to-right flow works well for short processes and request paths. Top-to-bottom flow often fits narrow screens better. Preview both before committing.

Limit visual styling

Custom colors can conflict with dark mode or platform themes. Begin with the renderer’s defaults. Add styles only when they communicate meaning and remain readable in all required themes.

Keep source near its explanation

Store the Mermaid block in the same Markdown file when possible. That makes the prose and diagram change together in one review.

Mermaid vs a Static Image

Choose Mermaid when:

  • the diagram changes frequently;
  • source diffs are valuable;
  • the layout uses standard diagram types;
  • the publishing platform renders Mermaid reliably.

Choose SVG or PNG when:

  • the design requires precise manual layout;
  • the destination does not render Mermaid;
  • the exact appearance must remain fixed;
  • external sharing requires a standalone asset.

A useful hybrid is to maintain Mermaid source and export an SVG for destinations that cannot render it. Keep the source beside the exported asset and document how to regenerate it.

Use Markdown to Image for shareable rendered Markdown content, or download SVG directly from the Mermaid Diagram Preview when the diagram itself is the asset.

FAQ

Is Mermaid part of standard Markdown?

No. A fenced mermaid block is an extension recognized by compatible applications and build systems. A basic Markdown parser may render it as ordinary code.

Does GitHub render Mermaid diagrams?

Yes. GitHub’s documentation describes Mermaid rendering in Markdown files and several collaboration surfaces. Test newer syntax because GitHub controls the deployed renderer and security settings.

Can I use Mermaid in Obsidian?

Obsidian’s official help documents Mermaid-style fenced diagram blocks in notes. Feature support can change with the application’s renderer, so verify complex or newly introduced diagram types in your installed version.

Can Mermaid replace architecture documentation?

No. A diagram is one view of a system. Pair it with decisions, ownership, constraints, failure behavior, and links to authoritative interfaces or schemas.

Why does my diagram render differently in dark mode?

Platforms may apply different Mermaid themes, CSS variables, fonts, and backgrounds. Avoid hard-coded colors until you have tested both themes.

Should I commit exported SVG files?

Commit an SVG when the publishing destination needs a static asset or the rendered result must remain stable. Also keep the Mermaid source and a documented regeneration process to prevent the two versions from drifting.

Is Mermaid safe for confidential diagrams?

Confidentiality depends on the editor and publishing workflow. WordToMD’s preview renders the diagram in your browser, but publishing the Markdown or SVG to a repository or site follows that destination’s access controls.

Conclusion

Mermaid makes diagrams maintainable because the source lives with the Markdown. Start with a small fenced block, choose the diagram type that matches the question, preview the syntax, and test it in the final renderer. Use prose to explain essential meaning and export SVG when a destination needs a static asset.

Try the examples in the Mermaid Diagram Preview, edit the surrounding documentation in the Markdown Editor, and keep the diagram focused enough that a future contributor can understand and update it without redrawing the entire page.