Markdown Mermaid: Diagrams & Flowcharts Guide

```mermaid
graph TD;
  A[Audio Input] --> B[Whisper VAD];
  B --> C[Markdown Note];
```

Architecture diagrams, systems workflows, customer journey maps, and sequence charts are vital components of technical documentation.

Traditionally, maintaining diagrams required external GUI tools like Visio, Figma, or Lucidchart, resulting in binary image exports that quickly become stale and are impossible to diff in Git.

Mermaid solves this by treating diagrams as code. By embedding plain-text diagram definitions inside standard Markdown fenced code blocks, your diagrams remain version-controllable, instantly editable, and permanently embedded in your notes.

In Oyma, GitHub, and Obsidian, Mermaid code compiles dynamically into interactive, hardware-accelerated vector graphics.

Basic Mermaid syntax: Flowcharts

To create a flowchart, use a fenced code block with the mermaid language identifier:

```mermaid
graph TD;
    A[Microphone Audio] --> B[ScreenCaptureKit Engine];
    C[System Audio Output] --> B;
    B --> D[On-Device Whisper VAD];
    D --> E[Structured Markdown Note];
```

Flowchart orientation

You control the layout direction on the first line:

• graph TD or flowchart TD: Top to bottom
• graph LR or flowchart LR: Left to right
• graph BT: Bottom to top
• graph RL: Right to left

Node shapes in flowcharts

Mermaid provides various node shapes using different brackets:

```mermaid
flowchart LR
    A[Square Box] --> B(Rounded Box)
    B --> C([Pill / Stadium])
    C --> D[(Cylinder / Database)]
    D --> E((Circle))
    E --> F{Diamond / Decision}
```

Sequence diagrams

Sequence diagrams illustrate interactions between components or actors over time:

```mermaid
sequenceDiagram
    autonumber
    actor User as User on macOS
    participant App as Oyma Desktop
    participant SCK as ScreenCaptureKit API
    participant Neural as Apple Neural Engine

    User->>App: Press Option+Cmd+R
    App->>SCK: Initialize system audio stream
    SCK-->>App: Raw audio buffers (16kHz)
    App->>Neural: Execute local Whisper model
    Neural-->>App: Text transcript chunks
    App->>User: Display live-preview transcript
```

State diagrams

State diagrams model the lifecycle states of an entity:

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Recording: Meeting detected
    Recording --> Processing: Call concluded
    Processing --> Summarizing: Whisper transcript complete
    Summarizing --> NoteSaved: LLM extracted action items
    NoteSaved --> [*]
```

Class diagrams

Class diagrams represent object-oriented structures and database models:

```mermaid
classDiagram
    class Note {
        +String title
        +Date updated
        +List~String~ tags
        +saveToDisk()
        +renderPreview()
    }
    class Vault {
        +String localPath
        +List~Note~ notes
        +buildFTS5Index()
    }
    Vault "1" *-- "many" Note : contains
```

Best practices for Mermaid diagrams in notes

1. Keep diagrams focused: Large diagrams with dozens of nodes become hard to read on mobile devices or smaller laptop screens. Break complex systems into multiple smaller diagrams.
2. Quote special characters: When node text contains parentheses or brackets, wrap the label in double quotes: id["User Interface (macOS)"].
3. Use meaningful node IDs: Use descriptive IDs (e.g., clientApp --> localServer) rather than generic letters (A --> B) to make plain-text maintenance easier.

Mermaid diagrams in Oyma on macOS

In Oyma:

• Mermaid blocks render automatically as crisp Retina SVG graphics.
• The diagram theme dynamically adapts to macOS system appearance, using optimal contrast for light and dark modes.
• Clicking the diagram lets you inspect the underlying plain text for rapid updates.
• All diagrams remain 100% standard plain text on your Mac disk, versionable with Git.

Frequently asked questions

What is Mermaid in Markdown?

Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired plain text to generate complex diagrams dynamically. It allows creating flowcharts, sequence diagrams, Gantt charts, and class diagrams directly inside fenced code blocks.

How do I embed a Mermaid diagram in a Markdown note?

Enclose your Mermaid diagram code inside a standard fenced code block with the `mermaid` language identifier (` ```mermaid `).

What types of diagrams can be generated with Mermaid?

Mermaid supports flowcharts (`graph TD` / `flowchart LR`), sequence diagrams (`sequenceDiagram`), state diagrams (`stateDiagram-v2`), class diagrams (`classDiagram`), entity relationship diagrams (`erDiagram`), user journey maps, and Git graphs.

How does Oyma render Mermaid diagrams in notes?

Oyma compiles Mermaid code in real time, rendering crisp SVG vector diagrams inside the live-preview editor while preserving the raw plain text in your Markdown file.