Mermaid syntax examples provide a powerful yet accessible way to create diagrams directly from text. This plain-text approach allows developers and technical writers to visualize complex workflows, processes, and structures without leaving their markdown editors. Understanding the core syntax is the first step to mastering Mermaid, as it unlocks the ability to translate abstract ideas into clear, communicative diagrams.
Foundational Structure and Basic Flowcharts
At its simplest, Mermaid uses a directional approach to diagram creation, defining nodes and the connections between them. The syntax relies on a graph structure, where you declare the direction (TD for top-down, LR for left-to-right, RL for right-to-left, or BT for bottom-top) and then list the nodes. Connections are established using arrows, making the logic of the flow immediately apparent to both the reader and the renderer.
Defining Nodes and Links
Every Mermaid diagram starts with the declaration of the graph type and direction. Following this, you define individual identifiers for your nodes. These identifiers are then linked using the arrow syntax, where --> represents a standard directional flow. This method allows for the rapid prototyping of simple sequences, such as user journeys or linear processes, with minimal code.
Advanced Syntax for Complex Diagrams
While basic flowcharts are essential, Mermaid truly shines when handling more complex structures like class diagrams or state machines. Here, the syntax expands to accommodate specific formatting rules, such as the use of parentheses for class definitions or specific keywords for state transitions. Mastering these nuances allows you to create highly detailed and specific visual representations of your system's architecture.
Styling and Configuration
Mermaid provides built-in configuration options to control the appearance of your diagrams without needing external CSS. You can set the theme, adjust the direction, and even define specific styles for individual nodes using the %%{init: {'theme':'dark'}}%% configuration block at the top of your script. This level of control ensures that your diagrams align perfectly with your documentation's branding and readability requirements.
| Syntax Element | Description | Use Case |
|---|---|---|
| TD / LR / RL / BT | Defines the direction of the graph layout | Organizing space for optimal readability |
| id1 --> id2 | Creates a directional link between two nodes | Showing flow or dependency |
| click id url "tooltip" | Adds hyperlink functionality to nodes | Connecting diagrams to external resources |
Utilizing Subgraph and Grouping Logic
For enterprise-level diagrams, organization is key. Mermaid's subgraph functionality allows you to group related nodes together, creating clusters that visually represent modules or departments. This not only tidies up the visual space but also helps in understanding the relationship between different components of a large system. The syntax for subgraphs requires a clear start and end declaration, ensuring the renderer understands the boundaries of each group.
Integration with Modern Development Workflows
The strength of Mermaid syntax examples lies in their portability. Because the diagrams are defined in plain text, they integrate seamlessly into version control systems like Git. This means your architectural diagrams can evolve alongside your codebase, maintaining accuracy and reducing the risk of outdated documentation. Furthermore, many modern static site generators and markdown platforms natively support Mermaid, allowing for automated rendering of diagrams within your existing CI/CD pipeline.
