Mermaid Diagram
The Mermaid widget lets you embed live, rendered diagrams directly in your Theneo documentation using plain text syntax. No image uploads, no design tools -just write your diagram as code and Theneo renders it instantly.
How to Add a Mermaid Diagram
1
Open the widget menu
Type / on any empty line to open the widget menu.
2
Choose Mermaid Diagram
Find and select Mermaid Diagram from the list.
3
Write your diagram code
Write your diagram code in the code editor at the top - the live preview at the bottom updates as you type.
Diagram Types
Mermaid diagrams let you turn complex logic, data models, and system interactions into clear visuals that readers can understand at a glance. Instead of asking developers to mentally reconstruct a flow from paragraphs of text, a well-placed diagram makes the structure immediately obvious. This is especially valuable for authentication flows, error handling logic, database relationships, and any multi-step process where the order and branching of steps matters.
Each tab below covers one diagram type - what it's for, a real-world example, and the rendered output.
Mermaid supports additional diagram types beyond the examples covered in this guide. For the full syntax reference and a complete overview of all available diagram types, visit the official Mermaid documentation.
Flowchart is useful when your reader needs to understand how a system decides what to do. Any logic that branches — request validation, error handling, payment processing — is hard to follow in prose but immediately clear as a flowchart. It gives readers a high-level mental map before they dive into the details.
graph TD
A([User]) --> B[Send API Request]
B --> C{Auth Token Present?}
C -- No --> D[Return 401 Unauthorized]
C -- Yes --> E{Token Valid?}
E -- No --> F[Return 403 Forbidden]
E -- Yes --> G[Return 200 OK]State Diagram is useful when you need to show what an entity looks like at different points in time and what causes it to change. Rather than describing retry logic or status transitions in prose, a state diagram lets developers instantly see every possible state a resource can be in and all the paths between them — setting clear expectations without ambiguity.
stateDiagram-v2
[*] --> Pending : Event triggered
Pending --> Sending : Worker picks up
Sending --> Delivered : HTTP 2xx
Sending --> Failed : Timeout or error
Failed --> Retrying : Retry policy active
Retrying --> Delivered : Retry succeeds
Retrying --> Dead : Max retries exceeded
Delivered --> [*]
Dead --> [*]Sequence Diagram is useful whenever more than one system is talking to each other. It makes the order and direction of communication obvious — who initiates each call, what comes back, and when. Developers integrating with your API don't have to mentally reconstruct a flow from paragraphs of text; they can see the full exchange laid out step by step.
sequenceDiagram
autonumber
participant U as User
participant C as Client App
participant A as Auth Server
U->>C: Click "Login"
C->>A: Redirect to /authorize
A->>U: Show login screen
U->>A: Approve access
A-->>C: Return authorization code
C->>A: POST /token
A-->>C: Return access_token
C-->>U: Logged inER Diagram is useful for onboarding developers who need to understand your data model before they can effectively use your API. Instead of explaining in text that "a User belongs to an Organization which has a Subscription," a single diagram makes those relationships and field structures self-evident at a glance.
erDiagram
ORGANIZATION {
string id PK
string name
string plan
}
USER {
string id PK
string org_id FK
string email
string role
}
SUBSCRIPTION {
string id PK
string org_id FK
string status
}
ORGANIZATION ||--o{ USER : "has"
ORGANIZATION ||--|| SUBSCRIPTION : "holds"Interactive controls
When a published Mermaid diagram is clicked, it opens in an interactive view with the following controls:
Zoom in / Zoom out — Use the + and - buttons to zoom in and out on the diagram. This is especially useful for large or complex diagrams where the full structure is difficult to read at default scale.
Pan / Move — Click and drag anywhere on the diagram to move around it. This allows you to navigate to any part of the diagram freely without losing your zoom level.
These controls ensure that even detailed, multi-node diagrams remain fully readable in your published developer portal. Readers are never constrained to a fixed viewport.
What made this section helpful for you?
What made this section unhelpful for you?
On this page
- Mermaid Diagram