Mermaid Skill

1. mmdc vs revealjs Rendering Difference

%%{init}%% themeVariables work in mmdc PNG but are overridden by revealjs CSS at render time. Quarto revealjs injects CSS vars via mermaid-init.js defaultCSS:

Result: mmdc shows black text; revealjs shows faint/colored text.

2. Fix: Black Text in revealjs

Add CSS override to YAML include-in-header in .qmd file:

include-in-header:
  - existing-header.html
  - text: |
      <style>
      .mermaid text { fill: #000000 !important; }
      .mermaid .label { color: #000000 !important; }
      </style>

• .mermaid text targets SVG <text> elements
• .mermaid .label targets CSS-positioned labels

3. Verification

mmdc-only is insufficient. Use quarto render + HTML inspection:

mise exec -- quarto render slides/xxx.qmd --to revealjs
# Inspect _site/slides/xxx.html — search for mermaid SVG, check fill attributes

Or use the webapp-testing skill (Playwright) to screenshot the rendered slide.

4. sequenceDiagram Tips

4.1. %%{init}%% Config

%%{init: {'theme': 'base', 'themeVariables': {'textColor': '#000000', ...}, 'sequence': {'mirrorActors': false}}}%%

• mirrorActors: false — hides the duplicate bottom actor row, saves ~3 lines

4.2. Slide Capacity

~20 diagram content lines fit on a 1920x1080 revealjs slide with scrollable: true without overflow.

5. mmdc Command

Run mermaid CLI via nix comma operator:

, mmdc -i input.mmd -o output.png

Requires system Chrome:

PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" , mmdc -i input.mmd -o output.png

NOTE: Strip code fence markers — mmdc needs raw mermaid syntax (no ```{mermaid} wrapper).

6. revealjs Text Color Fix

%%{init}%% themeVariables do NOT work in revealjs — revealjs applies its own CSS variables after SVG generation, overriding any inline settings.

Working fix: override the CSS variables at :root level in YAML include-in-header:

:root {
  --mermaid-edge-color: #000000 !important; /* signal text */
  --mermaid-label-fg-color: #000000 !important; /* actor names */
  --mermaid-node-fg-color: #000000 !important; /* alt/loop labels */
}

Do NOT use .mermaid text { fill: #000000 !important; } — it is ineffective because revealjs renders mermaid client-side and CSS vars take precedence over static SVG fill.

Why [alt/else labels] appear black by default: they use --mermaid-node-fg-color which defaults to #000 — while signal text and actor names use different vars.

7. Coloring alt/loop/actor in sequenceDiagram (revealjs)

CSS class names (sourced from mermaid-init.js defaultCSS):

IMPORTANT limitation: alt and loop blocks share the same .loopLine CSS class. They cannot be styled with different colors without more invasive CSS.

Apply via include-in-header <style> block with !important.