Mermaid Diagrams¶

Create flowcharts, sequence diagrams, class diagrams and more in your Jekyll site using Mermaid's simple text-based syntax.

GitHub Pages Compatible — Works without custom server-side plugins!

A ```mermaid block renders to an SVG diagram in the browser. For example, the Quick Start guide's "choose your path" flowchart is a Mermaid block the theme renders automatically:

The Quick Start page with a Mermaid flowchart rendered below the intro, branching from "What's your goal?" into the install paths

Quick Start¶

Step 1: Enable Mermaid on Your Page¶

Add mermaid: true to your page's front matter:

---
title: "My Documentation Page"
mermaid: true
---

Step 2: Write Your Diagram¶

Use native markdown code blocks with mermaid as the language:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]
```

That's it! The diagram renders automatically.

Configuration¶

Site Configuration¶

The theme includes Mermaid support in _config.yml:

mermaid:
  src: '/assets/vendor/mermaid/mermaid.min.js'

How It Works¶

Front matter flag — mermaid: true enables Mermaid on the page
Conditional loading — Script only loads when needed
Client-side rendering — No server-side plugin required
Auto-initialization — Diagrams render on page load

Diagram Types¶

1. Flowcharts¶

The most common diagram type for documenting processes and workflows.

Directions:

TD / TB — Top to Bottom
BT — Bottom to Top
LR — Left to Right
RL — Right to Left

```mermaid
graph LR
    A[Input] --> B[Process]
    B --> C{Valid?}
    C -->|Yes| D[Success]
    C -->|No| E[Error]
```

Node Shapes:

Syntax	Shape	Use Case
`A[Text]`	Rectangle	Actions, steps
`A(Text)`	Rounded	Processes
`A{Text}`	Diamond	Decisions
`A((Text))`	Circle	Start/End
`A[[Text]]`	Stadium	Subroutines
`A[(Text)]`	Cylinder	Database

Link Types:

Syntax	Description
`-->`	Arrow
`---`	Line
`-.->`	Dotted arrow
`==>`	Thick arrow
`--\\|Text\\|-->`	Arrow with label

2. Sequence Diagrams¶

Perfect for documenting API calls, user interactions, and system communication.

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: Click button
    Browser->>Server: API request
    Server-->>Browser: JSON response
    Browser-->>User: Display result
```

Arrow Types:

Syntax	Description
`->>`	Solid line with arrowhead
`-->>`	Dotted line with arrowhead
`-x`	Solid line with cross
`--x`	Dotted line with cross
`-)`	Solid line with open arrow

3. Class Diagrams¶

Document code architecture and relationships.

```mermaid
classDiagram
    class JekyllSite {
        +String title
        +Array pages
        +build()
        +serve()
    }

    class Page {
        +String content
        +Hash frontMatter
        +render()
    }

    JekyllSite --> Page : contains
```

4. State Diagrams¶

Model state machines and workflows.

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Reject
    Published --> [*]
```

5. Entity Relationship Diagrams¶

Document database schemas.

```mermaid
erDiagram
    POST ||--o{ TAG : has
    POST {
        string title
        string content
        date published_at
    }
    TAG {
        string name
        string slug
    }
```

6. Pie Charts¶

Visualize data distributions.

```mermaid
pie title Page Views by Section
    "Blog" : 45
    "Docs" : 30
    "Tutorials" : 15
    "About" : 10
```

7. Gantt Charts¶

Project timelines and schedules.

```mermaid
gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Research        :a1, 2026-01-01, 30d
    Design          :a2, after a1, 20d
    section Phase 2
    Development     :a3, after a2, 45d
    Testing         :a4, after a3, 15d
```

8. Git Graphs¶

Visualize Git branching and commits.

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

Syntax Options¶

Option A: Native Markdown (Recommended)¶

Use fenced code blocks — cleanest and most portable:

```mermaid
graph TD
    A --> B
```

Option B: HTML Div¶

Use <div class="mermaid"> — works when markdown doesn't:

<div class="mermaid">
graph TD
    A --> B
</div>

When to Use Each¶

Use Case	Recommended
Normal documentation	Markdown code blocks
Complex diagrams	HTML div
Nested in HTML	HTML div
Maximum portability	Markdown code blocks

Styling and Themes¶

Available Themes¶

Mermaid supports several built-in themes:

mermaid.initialize({
  theme: 'default'  // or 'forest', 'dark', 'neutral', 'base'
});

Theme	Description
`default`	Blue color scheme
`forest`	Green color scheme
`dark`	Dark background
`neutral`	Grayscale
`base`	Minimal styling

Troubleshooting¶

Diagram Not Rendering¶

Symptom	Solution
Raw code shown	Add `mermaid: true` to front matter
Blank space	Check syntax in Live Editor
Script not loading	Verify CDN URL in `_config.yml`
Partial render	Check for syntax errors

Common Syntax Errors¶

Wrong: graph TD A -> B      (single arrow)
Right: graph TD A --> B     (double arrow)

Wrong: graph TD A[Text]B    (no arrow between nodes)
Right: graph TD A[Text] --> B

Wrong: flowchart TD         (in older Mermaid versions)
Right: graph TD             (more compatible)

Testing Locally¶

# Start Jekyll dev server
docker-compose up

# Check browser console for errors
# Open http://localhost:4000/your-page

Best Practices¶

Only enable when needed — use mermaid: true only on pages with diagrams
Keep diagrams simple — complex diagrams slow rendering
Test in Live Editor — use mermaid.live first
Add descriptions — complex diagrams need text explanations
Use clear labels — avoid abbreviations

Resources¶

Mermaid Documentation: mermaid.js.org
Live Editor: mermaid.live
Syntax Reference: Mermaid Syntax
Theme Configuration: Mermaid Theming

This guide is part of the Zer0-Mistakes Jekyll Theme documentation.

Technical Reference¶

For implementation details (how Mermaid v2 was integrated, file changes, test suite):

Mermaid Integration → docs/implementation/feature-change-log.md