Creating Mermaid Diagrams

Our documentation supports interactive, zoomable, and scrollable Mermaid diagrams.

Any diagram written in standard Mermaid syntax will automatically be wrapped in a zoomable toolbar viewport. You can also configure a custom initial zoom level per-diagram to optimize readability.

---

Interactive Zoom & Scroll Container

The layout container and scrollbars are completely automated. Authors only need to write standard ```mermaid code blocks.

Under the Hood: How the Scrollable Container is Made

1. Dynamic Injection: The theme setup script .vitepress/theme/index.ts hooks into the Vue lifecycle. For every .mermaid diagram, it dynamically injects:
   • An outer .mermaid-zoom-container wrapper.
   • A .mermaid-zoom-controls toolbar for interactive zooming.
   • A .mermaid-viewport scrollable block that houses the SVG.
2. Scroll Styling: The scroll container is styled globally in .vitepress/theme/custom.css:
   • It sets overflow: auto and a default max-height: 600px to prevent huge diagrams from taking up the entire screen height.
   • It includes customized dark-themed thin scrollbars for WebKit browsers to keep the look clean and consistent.
3. Interactive Features:
   • Controls Toolbar: Zoom In (+), Zoom Out (-), and Reset (↺) buttons scale the layout dimensions directly.
   • Mouse Wheel Zooming: Hold Ctrl + Scroll Wheel inside the diagram to zoom dynamically.

---

Configuring Per-Diagram Initial Zoom

To set a custom starting zoom factor for a diagram, wrap the Mermaid block in a div element with the data-zoom attribute:

<div data-zoom="1.15">

```mermaid
flowchart TB
    A --> B
```

</div>

Zoom Guidelines:

• Standard Layouts: If the diagram fits naturally, omit the wrapper (defaults to 1.0 or 100%).
• Dense/Complex Diagrams: For diagrams with many elements, set the starting zoom to a smaller value (e.g., data-zoom="0.3" or data-zoom="0.4") so the entire flow is visible on load.
• Large/Detailed Elements: If the diagram is compact but benefits from larger text, set the starting zoom to a larger value (e.g., data-zoom="1.15" or data-zoom="1.25").

---

Best Practices for Clean Layouts

Mermaid diagrams can quickly become cluttered or disorganized if not structured carefully. Follow these conventions to keep layouts compact and readable:

1. The Column Layout (Multi-Process Flows)

For PCBs or services running multiple concurrent tasks/interrupts, structure your flowcharts in side-by-side columns:

• Set the top-level diagram to Left-to-Right (flowchart LR).
• Set each major flow pathway as a separate subgraph.
• Set the internal direction of each subgraph to Top-to-Bottom (direction TB).

This ensures that each path flows vertically down the page, while the different paths sit next to each other, fitting standard widescreen viewports cleanly.

2. Styling Conventions

Use standard color classes to group nodes by process or severity:

• Blue: Control pathways / Settings
• Purple: Interrupts / RX paths
• Green: Periodic / TX paths
• Yellow: Immediate / Single commands
• Red: Error exits / Fail states
• Gray: Internal helpers

Example Class Definitions:

3. Cross-Subgraph Connections

To keep flows disorganized-free:

• Use dotted lines (-.->) for secondary connections (like cross-group helper calls) to visually separate them from the primary flow.
• If lines cross multiple columns in a messy way, consider adding descriptive text inside the nodes (e.g. Calls Enqueue Helper) instead of drawing visual arrows across the entire canvas.