Mermaid Diagrams

Create flowcharts, sequence diagrams, Gantt charts, class diagrams, and more — directly in your Markdown with a fenced code block.

Overview#

Mermaid is a JavaScript-based diagramming language that lets you create diagrams using plain text. In Papersmith, wrap any Mermaid code in a fenced code block tagged mermaid to render it live in the preview — and faithfully in the exported PDF.

```mermaid
flowchart LR
  A[Start] --> B[End]
```

Flowcharts#

Flowcharts are the most common diagram type. Use flowchart LR for left-to-right flow or flowchart TD for top-down. Nodes are defined inline; edges use -->, ---, or -.->.

Left-to-right#

```mermaid
flowchart LR
  A([Start]) --> B[Authenticate]
  B --> C[Load data]
  C --> D([Done])
```

Top-down with shapes#

```mermaid
flowchart TD
  A([Start]) --> B[Process data]
  B --> C{Valid?}
  C -- Yes --> D[Save result]
  C -- No --> E[Show error]
  D --> F([End])
  E --> F
```

Node shapes#

Edge types#

Sequence Diagrams#

Sequence diagrams show how objects or services interact over time. Use sequenceDiagram as the type keyword. Participants are declared with participant; messages use ->> (solid) or -->> (dashed/return).

```mermaid
sequenceDiagram
  participant U as User
  participant A as App
  participant D as Database

  U->>A: Submit form
  A->>D: INSERT record
  D-->>A: OK
  A-->>U: Success message
```

Common syntax#

Class Diagrams#

Class diagrams describe object-oriented structure — classes, their attributes and methods, and relationships. Use classDiagram.

```mermaid
classDiagram
  class Animal {
    +String name
    +int age
    +speak() void
  }
  class Dog {
    +fetch() void
  }
  class Cat {
    +purr() void
  }
  Animal <|-- Dog
  Animal <|-- Cat
```

Relationship types#

State Diagrams#

State diagrams model the lifecycle of an object or process through discrete states. Use stateDiagram-v2. [*] is the initial/terminal state.

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Loading : fetch()
  Loading --> Success : data received
  Loading --> Error : request failed
  Success --> Idle : reset
  Error --> Idle : retry
```

State diagram syntax#

Gantt Charts#

Gantt charts visualize project timelines and task dependencies. Use gantt. Tasks can be marked done, active, or crit (critical).

```mermaid
gantt
  title Project Timeline
  dateFormat YYYY-MM-DD
  section Design
    Wireframes   :done, 2024-01-01, 5d
    Mockups      :done, 2024-01-06, 7d
  section Build
    Frontend     :active, 2024-01-13, 10d
    Backend      :       2024-01-20, 10d
  section Launch
    Testing      :       2024-01-30, 5d
    Deploy       :       2024-02-04, 2d
```

Gantt syntax#

Pie Charts#

Pie charts show proportional data as slices. Use pie. Add an optional title on the first line.

```mermaid
pie title Browser Share
  "Chrome"  : 65
  "Safari"  : 19
  "Firefox" : 4
  "Edge"    : 4
  "Other"   : 8
```

Entity Relationship (ER) Diagrams#

ER diagrams describe database structure — entities (tables), their attributes, and relationships with cardinality. Use erDiagram.

```mermaid
erDiagram
  USER {
    int id PK
    string name
    string email
  }
  ORDER {
    int id PK
    int user_id FK
    float total
  }
  PRODUCT {
    int id PK
    string name
    float price
  }
  USER ||--o{ ORDER : places
  ORDER }o--|| PRODUCT : contains
```

Cardinality notation#

Mind Maps#

Mind maps display hierarchical information radiating from a central concept. Use mindmap. Indentation defines the hierarchy; double parentheses ((text)) render the root as a circle.

```mermaid
mindmap
  root((Papersmith))
    Editor
      Markdown
      KaTeX Math
      Mermaid Diagrams
    Export
      PDF
      Themes
    Features
      Live Preview
      Slash Commands
      Find & Replace
```

Timelines#

Timeline diagrams show chronological events. Use timeline. Each event is a date (or label) followed by a colon and the event description.

```mermaid
timeline
  title History of Markup Languages
  1989 : HTML invented by Tim Berners-Lee
  1996 : CSS first specification
  2004 : Markdown created by John Gruber
  2011 : Mermaid project started
  2012 : KaTeX released by Khan Academy
```

PDF Export Notes#

Mermaid diagrams export to PDF as vector SVG — they are crisp at any scale and fully preserved in the document. A few things to keep in mind:

• Theme: Diagrams always export using the neutral theme regardless of the editor dark/light setting, so they look clean on white paper.
• Width: Diagrams are scaled to fit the page width. Very wide diagrams (e.g., large left-to-right flowcharts) may be scaled down. Use flowchart TD (top-down) for diagrams with many nodes to keep them readable.
• Page breaks (Pro): To force a diagram onto its own page, add <!-- pagebreak --> on its own line before or after the code block.
• Unsupported types: Most Mermaid diagram types are supported. If a type fails to render, the code block will appear as preformatted text in the export.

Quick Reference#