Mermaid

Mermaid is a diagramming tool written in Javascript for drawing diagrams with plain text.

Mermaid is usually the best default diagram tool for this vault because it renders directly in Obsidian and is supported by Quartz through Obsidian-flavored Markdown. This means the diagram source can live directly in the note without needing to generate and commit a separate image file.

Use Mermaid when the diagram is part of the note and should stay easy to edit in Markdown.

Good use cases:

• Flowcharts
• Sequence diagrams
• State diagrams
• Class diagrams
• Entity relationship diagrams
• Git graphs
• Timelines

Flowchart

flowchart TD
    Idea[Idea] --> Note[Write note]
    Note --> Diagram[Add Mermaid diagram]
    Diagram --> Quartz[Render in Quartz]
    Diagram --> Obsidian[Render in Obsidian]

Sequence diagram

sequenceDiagram
    participant User
    participant App
    participant Database

    User->>App: Submit request
    App->>Database: Query data
    Database-->>App: Return rows
    App-->>User: Show response

State diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Reviewed
    Reviewed --> Published
    Published --> Archived

Mermaid vs PlantUML and Graphviz

Mermaid is the simplest choice when a diagram should render in Markdown-first tools like Obsidian and Quartz.

PlantUML is more powerful for detailed UML diagrams, but it usually needs a rendering step or external service.

Graphviz is strong for graph layout and network-style diagrams, but it also usually needs a rendering step to produce an image.

Rule of thumb:

• Use Mermaid first for notes, explanations, and lightweight diagrams
• Use PlantUML for detailed UML
• Use Graphviz when automatic graph layout matters more than Markdown-native rendering