Basic structure
All Mermaid diagrams follow a consistent structure:- Diagram type declaration - Specifies what type of diagram to create
- Diagram content - The actual diagram definition using diagram-specific syntax
- Optional frontmatter - YAML configuration placed before the diagram
flowchart LRis the diagram type declaration (flowchart with left-to-right direction)- The lines below define nodes and connections
Diagram type declarations
Every diagram begins with a declaration that tells Mermaid which parser to use. Common diagram types include:| Declaration | Diagram Type |
|---|---|
flowchart or graph | Flowchart |
sequenceDiagram | Sequence diagram |
classDiagram | Class diagram |
stateDiagram-v2 | State diagram |
erDiagram | Entity relationship diagram |
journey | User journey diagram |
gantt | Gantt chart |
pie | Pie chart |
gitGraph | Git graph |
mindmap | Mindmap |
timeline | Timeline |
quadrantChart | Quadrant chart |
Comments
You can add comments to your diagram code using%%. Anything after %% on a line is ignored by the parser:
Frontmatter configuration
Frontmatter allows you to configure individual diagrams using YAML metadata. Place it before your diagram code, enclosed in triple dashes (---):
Frontmatter syntax rules
- The opening
---must be the only characters on the first line - Use proper YAML syntax with consistent indentation
- Settings are case-sensitive
- Mermaid silently ignores misspellings, but malformed YAML will break the diagram
Common frontmatter options
- Title and display
- Theme configuration
- Layout options
- Diagram-specific
Directives
Directives provide an alternative way to configure diagrams using the%%{ }%% syntax:
Directives can be placed before or after the diagram type declaration. While frontmatter is generally preferred for its readability, directives are useful for quick theme or configuration changes.
Special characters and escaping
Some words and characters can break diagrams. Here are common issues and solutions:| Issue | Affected Diagrams | Solution |
|---|---|---|
| The word “end” | Flowcharts, Sequence | Wrap in quotes: "end" |
| Special characters in labels | All | Use quotes: ["Label with (special) chars"] |
| Nested shapes | Flowcharts | Use quotes to prevent parser confusion |
Example with special characters
Text length limits
Mermaid has a maximum text length limit of 50,000 characters for diagram definitions. Exceeding this limit will result in an error diagram.Line breaks in text
Different diagram types support line breaks in text using<br> or <br/>:
Best practices
- Use meaningful IDs - Give nodes descriptive identifiers for better readability
- Comment complex sections - Help others (and your future self) understand the diagram
- Prefer frontmatter over directives - Frontmatter is more readable and maintainable
- Quote special characters - When in doubt, use quotes around labels
- Validate syntax early - Use the Mermaid Live Editor to test diagrams
Next steps
Initialization
Learn how to initialize Mermaid in your application
Configuration
Explore configuration options and patterns
Theming
Customize the appearance of your diagrams
Diagram types
Explore specific diagram type syntax