mermaid-diagrams

Mermaid Diagrams

Portable Mermaid.js diagramming for architectural documentation. Not tied to any blog platform, theme, or rendering engine. Diagrams can be rendered via CLI, embedded in markdown, or served as HTML snippets.

When to Use

Load this skill when:

• Rendering C4 flowchart approximations after the C4 level and model have been chosen; use c4-diagramming for C4 modeling decisions
• Producing sequence diagrams for interaction flows
• Designing flowcharts for process documentation
• Building state/class/ER diagrams for specification
• Generating any diagram that needs to render in both agent-facing and human-facing contexts
• Reviewing whether a structurally valid Mermaid diagram is the right communication artifact for its audience and output surface

Do NOT load when:

• A plain text outline communicates the relationship more clearly than a diagram.
• The target renderer cannot execute Mermaid and no pre-rendering path is available.

PDF Output — Pre-render Required

Mermaid code blocks (mermaid) do NOT render in the Pandoc → HTML → Puppeteer PDF pipeline. The pipeline generates static HTML with no JavaScript execution.

For any diagram destined for PDF output:

1. Create the diagram as a standalone .mmd file
2. Pre-render to SVG: npx @mermaid-js/[email protected] -i diagram.mmd -o diagram.svg --width 800
3. Choose one embedding method: use raw inline SVG by default, or base64 data URIs when the renderer corrupts raw SVG.
4. Strip hardcoded max-width pixel values from the SVG tags
5. Use flowchart TD (portrait) not flowchart LR (landscape) — see references/portrait-layout.md
6. Add page-break divs before/after each full-page diagram

Do NOT leave ```mermaid code blocks in markdown that will go through Pandoc. They render as raw monospace text.

See references/pdf-rendering-pipeline.md for the full pipeline with Puppeteer setup, SVG styling fixes, and QA checklist.

Communication Review

Before authoring, state the audience, reader job, target surface, and intended read order. Choose the smallest diagram type and scope that supports that job. Keep abstraction, node shapes, edge semantics, labels, boundary treatment, and visual hierarchy consistent. Syntax validation and a successful render are necessary but not sufficient: a diagram can be valid Mermaid and still be the wrong communication artifact because it is too dense, hides the primary path, mixes representational conventions, or leaves the reader to infer uncertainty.