Mermaid Diagrams

Mermaid is a text-based diagramming tool that lets you create diagrams using simple text instead of drawing shapes manually. You write Mermaid syntax inside a fenced Markdown code block, and supported editors or documentation platforms automatically render it as a visual diagram.

For example, a few lines of Mermaid code can generate a flowchart, sequence diagram, class diagram, Gantt chart, or entity relationship (ER) diagram without using any external design software.

Because Mermaid diagrams are written as plain text, they can be edited in any text editor, tracked with Git, reviewed in pull requests, and maintained alongside the rest of your documentation. This makes Mermaid especially popular for software documentation, technical guides, API documentation, system architecture, and project planning.

Many teams create diagrams using traditional design tools, but those diagrams often become difficult to maintain as projects evolve.

With Mermaid, updating a workflow is as simple as editing a few lines of text. There's no need to reposition shapes, reconnect arrows, or export new image files whenever something changes.

Mermaid offers several advantages:

• Create diagrams directly inside Markdown documents.
• Keep diagrams under version control with Git.
• Review diagram changes in pull requests.
• Collaborate without sharing image files.
• Keep documentation and diagrams synchronized.
• Build reusable, easy-to-maintain technical documentation.

This text-based approach saves time and makes documentation easier to update, especially for developer teams working on rapidly changing projects.

Quick Comparison#

Mermaid diagrams are written inside a fenced code block using the mermaid language identifier. When a compatible Markdown editor or documentation platform detects this code block, it automatically renders the diagram.

For example:

```mermaid
flowchart TD
    Start --> End
```

If the platform doesn't support Mermaid, the code is displayed as plain text instead of a rendered diagram. Before using Mermaid in production documentation, it's a good idea to verify that your editor, documentation generator, or hosting platform supports Mermaid rendering.

We'll cover platform compatibility later in this guide. If you're unfamiliar with fenced code blocks, see Markdown Code Blocks to learn how they work.

Let's create a simple flowchart.

```mermaid
flowchart TD
    Start --> Login
    Login --> Dashboard
```

This diagram represents a basic login workflow. Each line defines a relationship between two connected nodes, allowing Mermaid to generate a visual flowchart automatically.

Conceptually, the workflow looks like this:

Start
  │
  ▼
Login
  │
  ▼
Dashboard

Although the example is simple, the same syntax can be expanded to build authentication flows, API workflows, onboarding processes, deployment pipelines, and many other technical diagrams.

Before building larger diagrams, it's helpful to understand what each part of a Mermaid diagram does.

The example below contains four basic elements used in almost every flowchart.

flowchart TD
    Start --> Login
    Login --> Dashboard

Once you understand these building blocks, creating larger diagrams becomes much easier.

flowchart#

The flowchart keyword tells Mermaid which type of diagram to generate.

Mermaid supports many diagram types—including sequence diagrams, class diagrams, entity relationship diagrams, state diagrams, Gantt charts, Git graphs, and user journeys—but every flowchart begins with the flowchart keyword.

TD#

TD stands for Top Down, meaning the diagram starts at the top and flows downward.

Mermaid also supports other layout directions:

Choosing the right direction helps keep diagrams readable, especially as they become more complex.

-->#

The arrow (-->) connects one node to another and represents the direction of the workflow.

For example:

Start --> Login

This tells Mermaid that the process moves from Start to Login. By connecting multiple nodes, you can describe complete workflows using only a few lines of text.

Node Names#

Labels such as:

Start
Login
Dashboard

are called nodes.

Nodes represent the individual steps, actions, users, systems, or objects within a diagram. Choosing short, descriptive node names makes diagrams easier to read and understand, particularly in larger technical documentation.

Mermaid has become a standard tool in modern technical documentation because diagrams are created from plain text instead of image files.

This approach offers several practical benefits:

• Edit diagrams with any text editor.
• Track every change using Git.
• Review diagram updates in pull requests.
• Keep diagrams alongside documentation.
• Reuse diagrams across projects.
• Update workflows without recreating images.

For developer teams, this means documentation stays accurate as software evolves. Instead of maintaining separate diagram files, the source code and documentation remain synchronized in the same repository.

Flowcharts are the most commonly used Mermaid diagram type because they clearly illustrate how a process moves from one step to the next.

Whether you're documenting an application, explaining an API workflow, mapping a business process, or designing a user journey, a flowchart often communicates the idea more effectively than several paragraphs of text.

Common use cases include:

• User authentication flows
• Website navigation
• API request workflows
• Business processes
• Order processing
• CI/CD pipelines
• Software documentation
• Decision trees

Because of their flexibility and simple syntax, flowcharts are usually the best starting point for anyone learning Mermaid.

Creating Your First Flowchart#

Every Mermaid flowchart begins with the flowchart keyword, followed by the direction of the diagram.

```mermaid
flowchart TD
    Start --> Login
    Login --> Dashboard
```

This simple example creates a top-to-bottom workflow where each arrow connects one step to the next.

Although the syntax is minimal, the same structure can be expanded into complex workflows containing decisions, branches, loops, and multiple processes.

Choosing the Diagram Direction#

The direction keyword controls how your flowchart is arranged on the page. Choosing the appropriate layout improves readability, especially for larger workflows.

Select the direction that best matches the way readers naturally follow the process.

Top to Bottom (TD)#

Top-to-bottom is the default Mermaid layout and the one you'll see most often in documentation.

```mermaid
flowchart TD
    Start --> Step1
    Step1 --> Step2
    Step2 --> Finish
```

This layout works best for tutorials, documentation, checklists, and sequential workflows because readers naturally scan from top to bottom.

Left to Right (LR)#

For wider workflows, a left-to-right layout often makes better use of screen space.

```mermaid
flowchart LR
    Home --> Products
    Products --> Checkout
    Checkout --> Success
```

This direction is commonly used for website navigation, customer journeys, application flows, and process diagrams with multiple stages.

Right to Left (RL)#

Right-to-left layouts are less common but useful when illustrating reverse workflows or systems that naturally flow in that direction.

Bottom to Top (BT)#

Bottom-to-top layouts display the process upward instead of downward. Although they're used less frequently, they can be helpful for specialized diagrams or reverse process visualizations.

Connecting Nodes#

Nodes are connected using arrows to represent the direction of a process. The standard connector is -->, which indicates that one step leads to the next.

For example:

```mermaid
flowchart TD
    Start --> Login
    Login --> Dashboard
```

By combining multiple connections, you can describe complete workflows ranging from simple login processes to complex application architectures.

Giving Nodes Better Names#

Clear node names make diagrams much easier to understand. Instead of using generic labels such as A, B, or C, choose names that describe the actual step or action.

Less descriptive:

A --> B

Better:

```mermaid
flowchart TD
    Visitor --> Login
    Login --> Dashboard
    Dashboard --> Reports
```

Meaningful node names improve readability, reduce confusion, and make larger diagrams easier to maintain.

Adding Text to Arrows#

Arrow labels explain what happens between two connected steps.

```mermaid
flowchart TD
    User -->|Signs In| Dashboard
```

Labels are especially useful when documenting:

• User actions
• API requests
• Approval workflows
• Business processes
• Data movement between systems

Short, descriptive labels make complex workflows much easier to follow.

Using Different Node Shapes#

Different node shapes help readers quickly recognize the purpose of each step within a workflow.

Using shapes consistently makes larger diagrams easier to scan and understand.

Shape Examples#

Rectangle

```mermaid
flowchart TD
    Login[Login Page]
```

Rounded Rectangle

```mermaid
flowchart TD
    Start(Start)
```

Circle

```mermaid
flowchart TD
    A((Success))
```

Diamond

```mermaid
flowchart TD
    Decision{Password Correct?}
```

Choose shapes based on the role each node plays rather than using the same shape throughout every diagram.

Building a Login Flow#

Let's combine multiple concepts into a practical authentication workflow.

```mermaid
flowchart TD
    Start --> Login
    Login --> Check{Valid Credentials?}
    Check -->|Yes| Dashboard
    Check -->|No| Error
    Error --> Login
```

This example demonstrates several Mermaid features at once, including process nodes, decision nodes, branching paths, and labeled connections. Similar workflows are commonly used in authentication systems, user onboarding, and application documentation.

Building an Online Shopping Flow#

Flowcharts are equally useful for documenting business processes.

```mermaid
flowchart LR
    Browse --> Cart
    Cart --> Checkout
    Checkout --> Payment
    Payment --> Confirmation
```

This workflow illustrates a typical e-commerce purchase journey. Similar diagrams are often used for checkout flows, order processing, customer journeys, and sales funnels.

💡 Pro Tip: Keep each diagram focused on a single process or concept. Instead of creating one large flowchart with dozens of nodes, split complex workflows into smaller diagrams. Smaller diagrams are easier to read, review, and maintain over time.

While flowcharts describe how a process moves, sequence diagrams explain how different users, applications, or services communicate over time.

They're widely used for documenting:

• API requests
• Authentication workflows
• Client-server communication
• Payment processing
• Microservices
• Event-driven systems

Example#

```mermaid
sequenceDiagram
    Client->>Server: Send request
    Server->>Database: Fetch data
    Database-->>Server: Return data
    Server-->>Client: JSON response
```

Sequence diagrams make it easier to understand the order of interactions between multiple systems, making them one of the most valuable diagram types for technical documentation.

Class diagrams visualize the structure of an object-oriented application by showing classes and the relationships between them.

They're commonly used for:

• Software architecture
• UML documentation
• Object-oriented design
• Development planning

Example#

```mermaid
classDiagram
    class User
    class Account

    User --> Account
```

As projects grow, class diagrams help developers understand how different components are connected without reading large amounts of source code.

ER diagrams model database structures by showing how tables relate to one another.

Typical use cases include:

• SQL database design
• Backend development
• Database documentation
• System architecture

Example#

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
```

ER diagrams provide a clear visual representation of relationships, making database schemas easier to design and maintain.

State diagrams illustrate how an object or process changes from one state to another throughout its lifecycle.

Common examples include:

• Order status
• User account states
• Approval workflows
• Device lifecycle
• Application state management

Example#

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Approved
    Approved --> Completed
```

They're especially useful when documenting workflows that depend on status changes.

Gantt charts focus on project schedules and task timelines rather than workflows.

They're frequently used by:

• Project managers
• Product teams
• Software developers
• Freelancers

Example#

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Planning
    Research :2026-06-01, 5d

    section Development
    Coding :2026-06-06, 10d
```

Gantt charts make it easy to visualize project progress, deadlines, and task dependencies.

Pie charts display data as percentages, making them useful for comparing portions of a whole.

Common examples include:

• Website traffic
• Survey results
• Budget allocation
• Market share

Example#

```mermaid
pie
    title Traffic Sources
    "Organic Search" : 60
    "Direct" : 20
    "Social Media" : 20
```

Pie charts quickly communicate proportional data without requiring complex visualizations.

Git Graphs visualize commit history, branches, merges, and development workflows.

They're particularly useful for:

• Git tutorials
• Open-source projects
• Team onboarding
• Development documentation

Example#

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature
```

Visualizing branching strategies makes Git workflows much easier for new contributors to understand.

User Journey diagrams map the experience of a user as they interact with a product or service.

They're commonly used by:

• UX designers
• Product managers
• Business analysts
• Development teams

Example#

```mermaid
journey
    title User Registration
    section Sign Up
      Create Account: 5: User
      Verify Email: 4: User
    section First Login
      Access Dashboard: 5: User
```

These diagrams help teams understand user behavior, identify friction points, and improve the overall user experience.

If you're just getting started with Mermaid, begin with Flowcharts. They're the easiest to learn and cover most documentation needs.

One of Mermaid's biggest strengths is its broad support across modern Markdown editors, documentation frameworks, and developer platforms.

Instead of exporting diagrams as images, you can keep them directly inside your Markdown files, making documentation easier to edit, review, and version.

However, Mermaid diagrams only render on platforms that support the Mermaid syntax. On unsupported platforms, the diagram will appear as plain text.

Before adding Mermaid to production documentation, verify that your editor or publishing platform supports the required Mermaid version.

Where Can You Use Mermaid Diagrams?#

The following platforms provide Mermaid support, although the implementation may vary depending on the application version or configuration.

If you're unsure whether a platform supports Mermaid, create a small test diagram before adding larger diagrams to your documentation.

GitHub includes native Mermaid support, allowing diagrams to live alongside your documentation without creating separate image files.

This is particularly useful for:

• Project documentation
• README files
• Architecture diagrams
• Development workflows
• Open-source projects

Keeping diagrams in Markdown makes them easier to review in pull requests, track with Git, and update as your project evolves.

Related: See GitHub Flavored Markdown to learn about GitHub-specific Markdown features, README formatting, task lists, tables, and Mermaid support.

Obsidian includes built-in Mermaid support, making it easy to combine notes, diagrams, and documentation inside the same knowledge base.

Many users rely on Mermaid for:

• Personal knowledge management
• Study notes
• Software architecture
• Project planning
• Technical documentation

Because everything remains in Markdown format, diagrams stay portable, searchable, and easy to maintain.

Related: Read Obsidian Markdown to learn about internal links, backlinks, graph view, vault organization, and note management.

Visual Studio Code is one of the most popular environments for writing Markdown documentation.

Combined with Markdown preview and Mermaid-compatible extensions, VS Code allows developers to edit documentation and preview diagrams without switching applications.

This workflow is especially useful for documentation repositories, developer guides, and software projects.

Related: See VS Code Markdown for keyboard shortcuts, live preview, recommended extensions, and productivity tips.

Following a few simple practices makes Mermaid diagrams easier to understand and maintain.

• Keep each diagram focused on a single workflow or concept.
• Use clear, descriptive node names instead of generic labels.
• Maintain a consistent direction and naming style throughout your documentation.
• Split large workflows into multiple smaller diagrams.
• Add a short explanation before or after each diagram to provide context.
• Update diagrams whenever the underlying process changes.

Simple diagrams are usually more valuable than highly detailed ones because readers can understand them much faster.

Most Mermaid rendering issues are caused by a few simple mistakes.

• Forgetting to wrap the diagram inside a mermaid fenced code block.
• Using the wrong diagram keyword (such as flowchart, sequenceDiagram, or classDiagram).
• Connecting nodes incorrectly or introducing syntax errors.
• Creating diagrams that are too large to read comfortably.
• Assuming every Markdown editor supports Mermaid rendering.

If a diagram doesn't render correctly, check the syntax first, then verify that your editor or documentation platform supports the Mermaid version you're using.

If your diagram isn't rendering correctly, review this checklist:

• Is the diagram inside a mermaid fenced code block?
• Did you use the correct diagram type?
• Are all nodes and arrows connected correctly?
• Does your Markdown editor or documentation platform support Mermaid?
• Are there any syntax or spelling mistakes?
• Are you using a Mermaid feature supported by your platform's version?

Most rendering problems can be resolved by checking these basics before looking for more advanced issues.

As your documentation grows, these practices help keep diagrams clear and maintainable.

• Keep node labels short and descriptive.
• Create one diagram for one concept instead of combining multiple workflows.
• Use consistent naming across all diagrams.
• Update diagrams whenever the related documentation changes.
• Store Mermaid files in version control so changes can be reviewed alongside your documentation.

Well-maintained diagrams are easier to understand, easier to update, and far more valuable than overly complex visualizations.

The fastest way to learn Mermaid is by building diagrams yourself.

Try these exercises:

• Create a simple flowchart using three connected nodes.
• Build a login workflow with a decision node.
• Create a sequence diagram showing an API request.
• Design a small database using an ER diagram.
• Build a Git Graph to visualize a feature branch.

Practice each example in the Markdown Editor and compare your output with the examples throughout this guide.

Keep the Markdown Cheat Sheet open for quick syntax lookup.

Mermaid makes it easy to create professional diagrams directly from plain text inside Markdown documents.

Throughout this guide, you learned how to create flowcharts, sequence diagrams, class diagrams, entity relationship diagrams, state diagrams, Gantt charts, Git Graphs, pie charts, and user journey diagrams. You also explored platform compatibility, best practices, troubleshooting techniques, and practical examples for real-world documentation.

Because Mermaid diagrams are version-controlled, easy to maintain, and written alongside your documentation, they have become a standard choice for software teams, technical writers, educators, and open-source projects.

Whether you're documenting an API, planning a project, designing a database, or explaining a workflow, Mermaid helps you create documentation that's easier to understand and maintain.