How to add Mermaid diagrams to your Ghost blog

Diagrams can transform a wall of text into something instantly understandable. Whether you're explaining a workflow, showing system architecture, or mapping out a decision tree - a visual beats a paragraph every time.

Mermaid is a JavaScript library that turns simple text into professional diagrams. And with a quick code injection, you can use it in any Ghost article.

What is Mermaid?

Mermaid lets you create diagrams using a markdown-like syntax. Instead of dragging boxes around in a design tool, you write simple text - and Mermaid renders it as an SVG diagram.

For example, this text:

graph LR;
    A[Write text] --> B[Mermaid renders it] --> C[Beautiful diagram];

Becomes a flowchart showing three connected steps:

Why use Mermaid in Ghost?

• Version control friendly - Diagrams are just text, so they live in your content
• Easy to update - Change a label? Edit a word, not a design file
• Consistent styling - All diagrams match automatically
• No external tools - Create diagrams right in your Ghost editor
• Responsive - SVG diagrams scale perfectly on any device

Setting up Mermaid in Ghost

You only need to do this once. After setup, Mermaid will work on every post and page.

Step 1: Open code injection

1. Log into your Ghost Admin panel
2. Go to Settings → Code injection
3. You can use either Site header or Site footer (footer is slightly better for page load performance, but both work)

Step 2: Add the Mermaid script

Paste this code into your chosen code injection box:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
    document.addEventListener('DOMContentLoaded', function() {
        mermaid.initialize({ 
            startOnLoad: true, 
            theme: 'default',
            securityLevel: 'loose'
        });
    });
</script>

Step 3: Save

Click Save in the top right corner. That's it - Mermaid is now active on your site.

Tip: If you only want Mermaid on specific posts (not site-wide), you can add the script directly to an individual post. Use an HTML card at the end of your post and paste the same script there. This way, Mermaid only loads on posts that actually use diagrams.

Here's the process visualized:

Configuration options

You can customize Mermaid's behavior by changing the initialize options:

Example with dark theme:

<script>
    document.addEventListener('DOMContentLoaded', function() {
        mermaid.initialize({ 
            startOnLoad: true, 
            theme: 'dark',
            securityLevel: 'loose'
        });
    });
</script>

How to add diagrams in posts

In the Ghost editor, use an HTML card to add Mermaid diagrams:

1. Click the + button to add a card
2. Select HTML
3. Paste your Mermaid code wrapped in a <div class="mermaid"> tag

Template:

<div class="mermaid">
graph TD;
    A[Your diagram here];
</div>

Important: Add semicolons at the end of each line. Ghost's HTML processing requires this for Mermaid to render correctly.

Flowchart basics

Flowcharts are the most common diagram type. They show processes, decisions, and connections.

Direction options

Mermaid flowcharts can flow in four directions:

Vertical flowchart (top to bottom)

Code:

graph TD;
    A[Start] --> B{Is it working?};
    B -->|Yes| C[Great!];
    B -->|No| D[Debug];
    D --> B;

Result:

Horizontal flowchart (left to right)

Code:

graph LR;
    A[Input] --> B[Process] --> C[Output];
    B --> D[Log];

Result:

Node shapes

Different shapes convey different meanings:

Code:

graph TD;
    A[Rectangle - Process];
    B(Rounded - Start/End);
    C{Diamond - Decision};
    D[(Database)];
    E((Circle));

Result:

Arrow types

Code:

graph LR;
    A[Start] --> B[Arrow];
    A --- C[Line];
    A -.-> D[Dotted];
    A ==> E[Thick];
    A --label--> F[With text];

Result:

Practical examples

User signup flow

Code:

graph TD;
    A[User visits signup page] --> B[Enters email and password];
    B --> C{Valid input?};
    C -->|No| D[Show error message];
    D --> B;
    C -->|Yes| E[Create account];
    E --> F[Send verification email];
    F --> G[User clicks verify link];
    G --> H{Link valid?};
    H -->|Yes| I[Account activated];
    H -->|No| J[Show expired message];
    I --> K[Redirect to dashboard];

Result:

API request flow (horizontal)

Code:

graph LR;
    A[Client] -->|HTTP Request| B[Load Balancer];
    B --> C[Server 1];
    B --> D[Server 2];
    C --> E[(Database)];
    D --> E;
    E -->|Response| C;
    E -->|Response| D;
    C -->|JSON| A;
    D -->|JSON| A;

Result:

Content publishing workflow

Code:

graph TD;
    A[Draft] --> B[Write content];
    B --> C[Internal review];
    C --> D{Approved?};
    D -->|No| E[Revisions needed];
    E --> B;
    D -->|Yes| F[Schedule post];
    F --> G[Publish];
    G --> H[Promote on social];
    G --> I[Send newsletter];

Result:

Sequence diagrams

Sequence diagrams show interactions between different actors over time. Perfect for API documentation, user journeys, or system interactions.

Basic syntax

Code:

sequenceDiagram;
    participant A as User;
    participant B as Server;
    participant C as Database;
    A->>B: Login request;
    B->>C: Check credentials;
    C-->>B: User found;
    B-->>A: Login successful;

Result:

Arrow types in sequence diagrams

E-commerce checkout example

Code:

sequenceDiagram;
    actor Customer;
    participant Cart;
    participant Payment;
    participant Inventory;
    participant Email;
    Customer->>Cart: Add items;
    Customer->>Cart: Proceed to checkout;
    Cart->>Payment: Process payment;
    Payment-->>Cart: Payment confirmed;
    Cart->>Inventory: Reserve items;
    Inventory-->>Cart: Items reserved;
    Cart->>Email: Send confirmation;
    Email-->>Customer: Order confirmation;

Result:

With loops and conditions

Code:

sequenceDiagram;
    participant User;
    participant API;
    participant Cache;
    participant DB;
    User->>API: Request data;
    API->>Cache: Check cache;
    alt Cache hit
        Cache-->>API: Return cached data;
    else Cache miss
        API->>DB: Query database;
        DB-->>API: Return data;
        API->>Cache: Store in cache;
    end
    API-->>User: Return response;

Result:

Gantt charts

Gantt charts visualize project timelines. Great for roadmaps, project planning, or showing development phases.

Basic Gantt chart

Code:

gantt
    title Project timeline
    dateFormat YYYY-MM-DD
    section Planning
    Research           :a1, 2024-01-01, 7d
    Requirements       :a2, after a1, 5d
    section Development
    Backend API        :b1, after a2, 14d
    Frontend UI        :b2, after a2, 14d
    Integration        :b3, after b1, 7d
    section Launch
    Testing            :c1, after b3, 7d
    Deployment         :c2, after c1, 3d

Result:

Task status indicators

Code:

gantt
    title Blog launch checklist
    dateFormat YYYY-MM-DD
    section Content
    Write posts        :done, w1, 2024-01-01, 14d
    Edit and review    :active, w2, after w1, 7d
    Add images         :w3, after w2, 3d
    section Technical
    Set up Ghost       :done, t1, 2024-01-01, 3d
    Configure theme    :done, t2, after t1, 5d
    Set up analytics   :t3, after t2, 2d
    section Launch
    Final review       :crit, l1, after w3, 2d
    Go live            :milestone, l2, after l1, 0d

Result:

Status keywords:

• done - Completed (grey)
• active - In progress (blue)
• crit - Critical path (red)
• milestone - Zero-duration marker

Pie charts

Simple pie charts for showing proportions.

Code:

pie showData
    title Blog traffic sources
    "Organic search" : 45
    "Social media" : 25
    "Direct" : 15
    "Referral" : 10
    "Email" : 5

Result:

State diagrams

State diagrams show how a system transitions between different states. Useful for documenting user account states, order status, or any state machine.

Code:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Draft: Request changes
    Review --> Approved: Approve
    Approved --> Published: Publish
    Published --> Archived: Archive
    Archived --> [*]
    Published --> Draft: Unpublish

Result:

Order status example

Code:

stateDiagram-v2
    [*] --> Pending: Order placed
    Pending --> Processing: Payment confirmed
    Pending --> Cancelled: Customer cancels
    Processing --> Shipped: Items dispatched
    Processing --> Cancelled: Out of stock
    Shipped --> Delivered: Package received
    Shipped --> Returned: Customer returns
    Delivered --> [*]
    Returned --> Refunded
    Refunded --> [*]
    Cancelled --> [*]

Result:

Entity relationship diagrams

ER diagrams show database structure and relationships. Essential for technical documentation.

Code:

erDiagram
    USER ||--o{ POST : writes
    USER ||--o{ COMMENT : writes
    POST ||--o{ COMMENT : has
    POST }o--o{ TAG : has
    USER {
        int id PK
        string email
        string name
        datetime created_at
    }
    POST {
        int id PK
        int user_id FK
        string title
        text content
        datetime published_at
    }
    COMMENT {
        int id PK
        int user_id FK
        int post_id FK
        text content
    }
    TAG {
        int id PK
        string name
        string slug
    }

Result:

Relationship notation:

• ||--|| - One to one
• ||--o{ - One to many
• }o--o{ - Many to many

Styling your diagrams

Using themes

Change the theme in your code injection:

<script>
    mermaid.initialize({ 
        startOnLoad: true, 
        theme: 'forest'  // Try: default, dark, forest, neutral
    });
</script>

Custom styling with CSS

Add custom styles in your site header code injection:

<style>
    /* Make all Mermaid diagrams centered */
    .mermaid {
        text-align: center;
        margin: 2rem 0;
    }
    
    /* Custom node colors */
    .mermaid .node rect {
        fill: #f0f4f8;
        stroke: #4a5568;
    }
    
    /* Custom edge/arrow colors */
    .mermaid .edgePath path {
        stroke: #4a5568;
    }
</style>

Inline styling

You can also style individual nodes directly in your diagram:

Code:

graph LR;
    A[Default];
    B[Success]:::success;
    C[Warning]:::warning;
    D[Error]:::error;
    A --> B --> C --> D;
    classDef success fill:#10b981,color:#fff;
    classDef warning fill:#f59e0b,color:#fff;
    classDef error fill:#ef4444,color:#fff;

Result:

Troubleshooting

Diagram not rendering

Check these common issues:

1. Missing script - Verify the Mermaid script is in your code injection
2. Wrong wrapper - Use <div class="mermaid"> not <code> or <pre>
3. Missing semicolons - Add ; at the end of each line in flowcharts and sequence diagrams
4. Syntax error - Test your diagram at mermaid.live
5. Cache - Hard refresh your page (Ctrl+Shift+R)

Diagram too small or cut off

Add CSS to your code injection:

<style>
    .mermaid svg {
        max-width: 100%;
        height: auto;
    }
</style>

Special characters causing issues

Escape special characters in labels:

A["Label with (parentheses)"];
B["Label with 'quotes'"];
C["Label with #hash"];

Quick reference

Flowchart directions

Node shapes

Arrows

Conclusion

Mermaid transforms how you communicate complex ideas in your Ghost blog. With just a few lines of text, you can create flowcharts, sequence diagrams, Gantt charts, and more - no design tools required.

Start simple with a basic flowchart, then explore other diagram types as you need them. The Mermaid documentation has even more options and examples.

Happy diagramming!