majesticlabs-dev Mermaid Builder
Core Philosophy
- Correctness: Follow Mermaid syntax rules strictly
- Clarity: Diagrams communicate complex ideas simply
- Simplicity: Avoid overloading with unnecessary detail
- Modularity: Break complex diagrams into subgraphs
Critical: Label Quoting Rule
RULE: Wrap labels in double quotes if they contain spaces, special characters, or punctuation.
%% CORRECT - labels with spaces quoted
flowchart LR
A["User Login"] --> B["Process Request"]
C["Pay $100?"] --> D["Confirm (Yes/No)"]
%% WRONG - will fail to render
flowchart LR
A[User Login] --> B[Process Request]
Must quote: Spaces, special chars ($%&), punctuation (:,;), operators (()[])
Optional: Simple alphanumeric (Login, Process, Node1)
When in doubt, use quotes. It never hurts.
Quick Reference
Flowchart Shapes
| Syntax | Shape |
|---|---|
["Text"] |
Rectangle |
("Text") |
Rounded |
{"Text"} |
Diamond (decision) |
[("Text")] |
Cylinder (database) |
(("Text")) |
Circle |
Arrow Types
| Syntax | Type |
|---|---|
--> |
Solid arrow |
--- |
Solid line |
-.-> |
Dotted arrow |
==> |
Thick arrow |
| `--> | Label |
Diagram Types
| Type | Declaration | Use Case |
|---|---|---|
| Flowchart | flowchart TD |
Processes, workflows, decisions |
| Sequence | sequenceDiagram |
Component interactions, API flows |
| Class | classDiagram |
OOP structure, models |
| State | stateDiagram-v2 |
State transitions |
| Gantt | gantt |
Timelines, scheduling |
| ER | erDiagram |
Database schema |
| Pie | pie |
Proportional data |
Directions: TB/TD (top-down), BT (bottom-up), LR (left-right), RL (right-left)
See references/diagram-examples.md for complete examples of each diagram type.
Minimal Examples
Flowchart
flowchart TD
Start["Start"] --> Check{Valid?}
Check -->|Yes| Process["Process"]
Check -->|No| Error["Error"]
Process --> End["End"]
Sequence
sequenceDiagram
Client->>Server: Request
Server-->>Client: Response
ER Diagram
erDiagram
USER ||--o{ ORDER : "places"
USER { int id PK string email }
ORDER { int id PK int user_id FK }
Subgraphs for Organization
flowchart TD
subgraph "Frontend"
A["UI"]
end
subgraph "Backend"
B["API"]
C[("DB")]
end
A --> B --> C
Styling
flowchart TD
A["Success"] --> B["Error"]
classDef successStyle fill:#C8E6C9,stroke:#388E3C
classDef errorStyle fill:#FFCDD2,stroke:#D32F2F
class A successStyle
class B errorStyle
Common Errors to Avoid
| Error | Wrong | Correct |
|---|---|---|
| Unquoted spaces | A[User Login] |
A["User Login"] |
| Invalid arrow | A -> B |
A --> B |
| Unquoted special | A[Cost: $100] |
A["Cost: $100"] |
| Missing bracket | A["Node --> B |
A["Node"] --> B |
Validation Checklist
- Labels with spaces are quoted
- Labels with special characters quoted
- Brackets properly matched
- Arrow syntax correct (
-->not->) - Node IDs unique and meaningful
- Comments explain complex sections
- Previewed without errors
Data Lineage Patterns
See references/data-lineage.md for:
- ETL pipeline patterns
- Multi-layer data architecture
- Cross-system data flows
- Database schema lineage
- Streaming data lineage
- Column-level lineage
Resources
Remember: The quoting rule is the #1 cause of Mermaid rendering failures. When in doubt, quote it.