Diagrams Guide

How to create, use, and maintain diagrams in the SMDS documentation (Mermaid and Draw.io).

Mermaid Diagrams

Mermaid diagrams can be rendered in two ways:

Option 1: Markdown code blocks (.md or .mdx)

Option 2: MermaidDiagram component (MDX, recommended)

If code blocks do not render, use the MermaidDiagram component in MDX files for reliable client-side rendering:

import MermaidDiagram from '@site/src/components/MermaidDiagram';

<MermaidDiagram value={`flowchart TB
    A[Start] --> B[Process]
    B --> C[End]
`} />

This keeps the diagram as source code (no SVG copy-paste) and gives full flexibility.

When to Use Mermaid

• Architecture overviews
• Process flows
• Data lineage
• Simple sequence diagrams

Best Practices

• Keep diagrams concise—avoid overly complex flows
• Use subgraph for logical groupings
• Prefer flowchart for process flows; use sequenceDiagram for API interactions

Reference

• Mermaid syntax

---

Draw.io Diagrams

Draw.io diagrams are designed in app.diagrams.net and exported as SVG for static display.

Workflow

1. Edit .drawio files in static/drawio/ (e.g. static/drawio/vendor/onboarding/01-record-initiation.drawio)
2. Export to SVG using the export script
3. Reference the SVG in MDX via ZoomableDiagram

Export Commands

# Export all Draw.io files
npm run drawio:export

# Export a single file
npm run drawio:export -- vendor/onboarding/01-record-initiation.drawio

# Export a folder
npm run drawio:export -- vendor/onboarding/

Requirements: Docker must be running. The script uses rlespinasse/drawio-export.

Using in MDX

import ZoomableDiagram from '@site/src/components/ZoomableDiagram';

<ZoomableDiagram
  src="/drawio/vendor/onboarding/01-record-initiation.svg"
  alt="Record Initiation Flow"
  drawioFile="vendor/onboarding/01-record-initiation.drawio"
/>

• src — path to the exported SVG (under /drawio/)
• alt — descriptive text for accessibility
• drawioFile — path to the .drawio source (enables download link)

Zoom and Full Screen

• Use the zoom controls (+, −) or full-screen icon on the diagram
• Full screen shows the diagram at full size; use browser zoom (Ctrl/Cmd +) if needed
• Press Escape or click outside to exit full screen

File Layout

• .drawio and .svg files live in the same folder (e.g. static/drawio/vendor/onboarding/)
• See static/drawio/vendor/onboarding/README.md for export workflow details

---

Diagram Conventions

Type	Use Case	Location
Mermaid	Architecture, process flows	Inline in .md / .mdx
Draw.io	Detailed flows, complex UI	static/drawio/ + MDX usage