Mermaid.js Syntax Basis

Before diving into specific architectural layouts like complex flowcharts or sequence timelines, it is essential to understand the foundational rules that govern the Mermaid Playbook. Mermaid relies on a clean, highly intuitive text notation system. Once you understand how the engine initializes a canvas type, names structural components, and routes directional arrows, writing any complex system layout becomes completely natural.

This quick primer covers the global structural syntax mechanics that apply across almost every Mermaid diagram type inside the VPasCode workspace.

1. The Mandatory Diagram Type Wrappers

Every single block of Mermaid code must begin by explicitly declaring its diagram archetype on the very first line. This tells the VPasCode parser exactly which structural engine to spin up in your preview canvas:

  • graph TD — Specifies a Flowchart layout organized from Top to Down.
  • sequenceDiagram — Specifies a chronological runtime Timeline chart.
  • classDiagram — Specifies a structural Object-Oriented software blueprint.

Unlike other text-to-diagram engines, Mermaid does not require trailing end-tags. The parser simply reads the structural declaration on line one and compiles everything nested directly below it within your code block container.

2. Declaring Elements: IDs vs. Display Labels

When modeling a software system, you will create various structural elements like components, databases, or microservices. In Mermaid, you declare an element by defining a short, internal alphanumeric ID, followed immediately by a bracket style that controls its visual shape, and a user-friendly display name:

microservice_id[Payment Processing API]
db_id[(User Transaction SQL)]

Why this is a best practice: Using a short, clean internal ID (like microservice_id) makes drawing relationship lines much faster later on. If you ever need to change the customer-facing label from “Payment Processing API” to “Global Checkout Service”, you only have to edit it in the single line where it is declared, rather than updating dozens of lines across your script.

3. Mastering Relationship Arrows and Directional Routing

Connections between system nodes are drawn using combinations of dashes (-), equal signs (=), and arrow brackets (>). The style of your lines gives you implicit control over how the automated layout engine scales your diagram:

  • A --> B draws a standard directed arrow pointing from element A straight to element B.
  • A --- B draws a flat, undirected link line with no arrow head, ideal for simple associations.
  • A -.-> B creates a dotted dependency line, which is the industry standard for indicating asynchronous dependencies or network webhooks.
  • A ==> B creates a thick, bolded connection line, perfect for highlighting primary data processing pathways or critical infrastructure links.

4. Adding Context Inline: Labels and Code Comments

Clear documentation relies heavily on putting appropriate context around your visual lines and text scripts:

Labeling Connection Lines

You can add explanatory text straight to any connection line by inserting the text string between two sets of dashes, or by appending a pipe character (|Text|) right after your relationship mapping:

client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_id

Writing Code Comments

If you want to leave an administrative note, design credit, or architectural explanation inside your script file without rendering a visual box on the canvas, use double percent signs (%%). This tells the engine to skip parsing that line entirely:

%% TODO: We need to update this boundary box once the DevOps migration finishes
[Legacy Monolith] --> [New Microservice]
Scroll to Top