By Patrick McCurley
Inline Explainer Blocks — Replacing Mermaid in Emberflow Docs
Emberflow documents now support `
The Format
An `
For architecture diagrams and flowcharts, use `type="diagram"` with declarative JSON — the platform auto-computes layout with dagre:
```html
<div class="explainer-placeholder"></div>Viewer Pipeline
The key challenge: `
Phase 1: Extract
Before the markdown hits marked.parse(), a regex finds all `
Design Tokens
All <explainer> blocks have access to Emberflow's CSS custom properties, which adapt to light/dark theme automatically:
| Token | Use |
|---|---|
--bg |
Page background |
--bg-secondary |
Card/panel backgrounds |
--text |
Body text |
--text-muted |
Secondary text, labels |
--border |
Borders, dividers |
--link |
Accent color (orange) |
--heading |
Heading text |
--code-bg |
Code block backgrounds |
Script Rules
Scripts inside <explainer> blocks follow strict conventions for compatibility:
- Use
var— notconstorlet - Use
function(){}— not arrow functions - Scope all queries to
container—container.querySelectorAll('.item') - Scripts run via
new Function('container', code)(vizEl)— no global scope pollution
What's Next
The <explainer> format is shared across Emberflow's content types. The explainer content type uses slides (left prose + right viz with navigation), while documents use inline blocks that flow with the markdown. Same viz engine, same design tokens, same primitives — two presentation modes.