instructions for mermaid diagrams

MARP-MERMAID-Readme.md

@@ -0,0 +1,153 @@
+# 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)