Enabling Mermaid Diagrams in Marp Slides

Mermaid diagrams (```mermaid code blocks) do not render natively in Marp. This document describes how to enable Mermaid support in the MakerFLOSS slide build pipeline.

Overview

Marp converts Markdown to HTML/PDF, but Mermaid requires JavaScript execution to render diagrams. The solution is to:

Configure Marp to transform mermaid code blocks into <div class="mermaid"> elements
Inject the Mermaid.js library into the generated HTML
Initialize Mermaid on page load

Setup Instructions

Step 1: Add Dependencies

Create or update package.json in the repository root:

{
  "name": "makerfloss-slides",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "./build-slides.sh"
  },
  "devDependencies": {
    "@marp-team/marp-cli": "^4.1.0",
    "@marp-team/marp-core": "^4.1.0"
  }
}

Install dependencies:

npm install

Step 2: Create Marp Configuration

Create marp.config.mjs in the repository root:

import { Marp } from '@marp-team/marp-core'

export default {
  html: true,
  engine: (constructorOptions) => {
    const marp = new Marp(constructorOptions)

    // Transform mermaid code blocks to divs that mermaid.js can render
    const { code } = marp.markdown.renderer.rules
    marp.markdown.renderer.rules.code = (tokens, idx, options, env, self) => {
      const token = tokens[idx]
      if (token.info.trim() === 'mermaid') {
        return `<div class="mermaid">${token.content}</div>`
      }
      return code(tokens, idx, options, env, self)
    }

    return marp
  }
}

Step 3: Update build-slides.sh

Modify build-slides.sh to use the config file when available:

CONFIG="$REPO_ROOT/marp.config.mjs"

if command -v npx &>/dev/null && [ -f "$CONFIG" ]; then
  npx @marp-team/marp-cli --config "$CONFIG" --html --output "$OUTPUT_DIR/" "${SLIDES[@]}"
elif command -v marp &>/dev/null; then
  marp --html --output "$OUTPUT_DIR/" "${SLIDES[@]}"
else
  # ... existing Docker fallback ...
fi

Step 4: Add Mermaid Script to Slides

In each Marp presentation that uses Mermaid diagrams, add the following after the frontmatter:

---
marp: true
theme: gaia
class: invert
paginate: true
---

<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, theme: 'dark' });
</script>

# Your Slide Title
...

Note: Use theme: 'dark' for dark Marp themes (like gaia with class: invert), or theme: 'default' for light themes.

Usage

After setup, build slides as usual:

# With npm
npm run build

# Or directly
./build-slides.sh

The generated HTML files in slides/ will render Mermaid diagrams when viewed in a browser.

Troubleshooting

Diagrams not rendering

Ensure the <script> tag is present in the slide markdown
Check browser console for JavaScript errors
Verify the Mermaid syntax is correct (test at https://mermaid.live)

Diagrams render as code blocks

Verify marp.config.mjs exists and is valid
Ensure --html flag is passed to marp-cli
Check that npx is available and package.json dependencies are installed

PDF export

Mermaid diagrams may not render in PDF exports since they require JavaScript. Options:

Use --html output and print to PDF from browser
Pre-render diagrams as SVG images using mermaid-cli:
```
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg
```
Then embed the SVG in your slides.

Alternative: Docker with Mermaid

If using the Docker fallback, you'll need a custom Docker image or mount the config file. The standard marpteam/marp-cli image does not include mermaid support out of the box.

3.9 KiB Raw Blame History