Setting Up MDBook with Mermaid and JotDown

This guide explains how to configure MDBook with Mermaid.js support to create interactive diagrams in documentation, and how we integrated JotDown for a seamless workflow between Notion and our documentation.

Prerequisites

  • Rust and Cargo installed
  • Node.js (for Mermaid.js)

MDBook Installation

  1. Install MDBook:
cargo install mdbook --version 0.4.40
  1. Install MDBook Mermaid plugin:
cargo install mdbook-mermaid --version 0.15.0

Configuration

  1. Create a book.toml file with:
[book]
title = "Documentation"
authors = ["Your Team"]

[preprocessor.mermaid]
command = "mdbook-mermaid"

[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]
  1. Download Mermaid.js v8.11.0:
curl -o mermaid.min.js https://cdn.jsdelivr.net/npm/mermaid@8.11.0/dist/mermaid.min.js
  1. Create mermaid-init.js:
window.mermaid.initialize({startOnLoad: true});

JotDown Integration

To streamline our workflow between Notion and our MDBook documentation, we integrated JotDown, which provided several key benefits:

Setting Up JotDown

  1. Clone and build the JotDown repository:
git clone https://github.com/Harry-027/JotDown
cd JotDown
cargo build --release
  1. Configure Notion API token in your environment:
export NOTION_TOKEN="your_notion_integration_token"
  1. Configure your MCP client (such as Claude desktop) to use JotDown for automated documentation generation.

Benefits of JotDown in Our Workflow

  • Content Synchronization: Automatically pulls content from Notion into our MDBook structure
  • Consistency: Maintains consistent formatting between Notion and MDBook
  • Automation: Reduces manual tasks in converting Notion pages to MDBook chapters
  • Efficiency: Significantly speeds up the documentation process

Usage

Add Mermaid diagrams in Markdown files:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Result]
    B -->|No| D[Alternative]
```

Supported Diagram Types

  • Flowcharts (graph)
  • Sequence diagrams (sequenceDiagram)
  • Class diagrams (classDiagram)
  • Gantt charts (gantt)
  • Pie charts (pie)

Troubleshooting

If diagrams don't render:

  1. Verify Mermaid.js version matches
  2. Check browser console for errors
  3. Ensure JavaScript files are properly linked

Version Compatibility

Tested with:

  • MDBook 0.4.40
  • mdbook-mermaid 0.15.0
  • Mermaid.js 8.11.0
  • JotDown (latest version)