153 lines
3.9 KiB
Markdown
153 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
1. Configure Marp to transform mermaid code blocks into `<div class="mermaid">` elements
|
|
2. Inject the Mermaid.js library into the generated HTML
|
|
3. Initialize Mermaid on page load
|
|
|
|
## Setup Instructions
|
|
|
|
### Step 1: Add Dependencies
|
|
|
|
Create or update `package.json` in the repository root:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Step 2: Create Marp Configuration
|
|
|
|
Create `marp.config.mjs` in the repository root:
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. Use `--html` output and print to PDF from browser
|
|
2. Pre-render diagrams as SVG images using mermaid-cli:
|
|
```bash
|
|
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.
|
|
|
|
## References
|
|
|
|
- [Marp CLI Documentation](https://github.com/marp-team/marp-cli)
|
|
- [Mermaid.js Documentation](https://mermaid.js.org/)
|
|
- [Marp Custom Engine](https://github.com/marp-team/marp-cli#custom-engine)
|