obsidian-mermaid

Obsidian Mermaid Diagrams

Create Mermaid diagrams that render correctly in Obsidian and publish without issues.

When to Use This Skill

Activate when you need to:

Create flowcharts, sequence diagrams, ER diagrams
Convert ASCII art to Mermaid
Fix Mermaid rendering errors in Obsidian

Core Principle: Simplicity First

A diagram should be graspable at a glance

Complex diagrams are hard to read. Always express only the essentials with the minimum number of nodes and connections.

Node Minimization

Before (9 nodes):

flowchart LR
    A[수집] --> B[정리] --> C[보관]
    D[목표] --> E[학습] --> F[실행] --> G[측정] --> H[달성]

After (2 nodes - sequential flow as text within nodes):

flowchart LR
    A[수집 → 정리 → 보관]
    B[목표 → 학습 → 실행 → 달성]

Connection Minimization

Express only the core flow, explain details in the body text
5 or fewer nodes, no crossing connection lines
Split complex relationships into multiple simple diagrams

Choosing Between Table vs Mermaid

Format	Purpose	Example
Table	Attribute-value mapping, comparison, options	Tasks by energy level
Mermaid	Flow, process, feedback loop	Input→Process→Output
Inline	Simple sequential flow	`A → B → C`

Principle: Choosing a format that expresses the same information more compactly

Critical Rules

1. NO Markdown in Labels

Common Errors:

Node["1. First"]     → "Unsupported markdown: list"
Node["Text<br/>More"] → "Unsupported markdown: heading"
Node["## Header"]    → "Unsupported markdown: heading"

Correct:

Node[First]
Node[Text]

Rule: Keep labels plain text. Move complex descriptions outside the diagram.

2. Prefer Square Layout

Problem: flowchart LRis too wide, and flowchart TBbecomes too long.

Solution: Create a layout close to a square by combining TB + internal LR

flowchart TB
    subgraph Layer1["레이어 1"]
        direction LR
        A[항목A] ~~~ B[항목B] ~~~ C[항목C]
    end

    subgraph Layer2["레이어 2"]
        direction LR
        D[항목D] ~~~ E[항목E]
    end

    Layer1 --> Layer2

Pattern:

flowchart TB: The overall flow goes top→bottom
direction LR: Each subgraph is arranged horizontally inside
~~~: Invisible connections (for alignment without arrows)

Rule: If it becomes too long vertically, use subgraph + direction LR use.

3. Keep Labels Short

❌ Too long:
Node["This is a very long description that will break layout"]

✅ Short and clear:
Node[Short Label]

Rule: Labels should be under 15 characters. Add details in text below the diagram.

4. Avoid Special Characters in Subgraph Names

❌ May cause issues:
subgraph "1. Phase One"
subgraph "Phase: Setup"

✅ Safe:
subgraph Phase_One["Phase One"]
subgraph Setup["Setup Phase"]

Good Examples

Simple Flowchart

flowchart TB
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Process Flow with Details Outside

flowchart TB
    Input[Input] --> Process[Process]
    Process --> Output[Output]

Process Details:

Input: User data from form
Process: Validation and transformation
Output: Saved to database

Subgraph Example

flowchart TB
    subgraph Frontend["Frontend"]
        UI[UI] --> API[API Call]
    end
    subgraph Backend["Backend"]
        Server[Server] --> DB[Database]
    end
    API --> Server

Bad Examples (Don't Do This)

Markdown in Labels

flowchart LR
    A["1. Start<br/>with details"] --> B{"2. Decision"}

This will show "Unsupported markdown" errors.

Too Wide

flowchart LR
    A[Very Long Process Name Here] --> B[Another Long Name] --> C[Yet Another] --> D[And More]

This gets cut off on mobile and narrow screens.

Converting ASCII to Mermaid

ASCII Art:

┌───────┐     ┌───────┐
│ Start │────→│  End  │
└───────┘     └───────┘

Mermaid:

flowchart TB
    Start[Start] --> End[End]

Quality Checklist

Before completing diagram creation:

No <br/> tags in node labels
No numbered list format (1., 2.) in labels
Square layout: Use TB + LR within subgraph
All labels are short (under 15 characters)
Complex details moved to text outside diagram
No special characters in subgraph names
Tested rendering in Obsidian preview