If you've ever needed to map out a network layout quickly for documentation, a team meeting, or a project proposal you know how painful it can be to open a full diagramming tool just to sketch a few connections. Mermaid syntax solves this problem by letting you write network diagrams in plain text. You describe the nodes and links, and a renderer turns that text into a visual diagram. No drag-and-drop, no mouse clicking, no licensing headaches. That's why understanding how to create a network architecture diagram using Mermaid syntax has become a practical skill for network engineers, DevOps teams, and technical writers alike.

What Is Mermaid Syntax, and Why Use It for Network Diagrams?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from text written in a simple, markdown-like syntax. It was originally created by Knut Sveidqvist and is now supported by platforms like GitHub, GitLab, Notion, and many documentation tools. Instead of placing boxes and drawing lines with a mouse, you write short declarative statements that define nodes and the connections between them.

For network architecture diagrams specifically, Mermaid uses a graph or flowchart block where you declare devices, links, and optional labels. The result is a clean, consistent diagram you can version-control alongside your code or documentation.

Here's why teams choose Mermaid for network diagrams:

  • Text-based workflow: Diagrams live in plain text files, so they work with Git, pull requests, and code review processes.
  • No software installation required: Mermaid runs in a browser, in documentation platforms, or through a simple CLI.
  • Consistent output: Every render looks the same regardless of who writes it, eliminating the style drift you get with manual diagramming.
  • Fast to update: Changing a connection or renaming a device takes seconds, not minutes of repositioning shapes.

How Do You Write a Basic Network Diagram in Mermaid?

A Mermaid network diagram starts with a graph declaration, followed by node definitions and link statements. Here's the structure:

graph TD
 Internet((Internet)) --> Firewall
 Firewall --> Switch_Core
 Switch_Core --> Server_Web1
 Switch_Core --> Server_Web2
 Switch_Core --> Server_DB

Let's break this down piece by piece:

  • graph TD declares a top-down flowchart. You can also use LR for left-to-right, BT for bottom-to-top, or RL for right-to-left.
  • Node names like Firewall and Switch_Core are identifiers. Mermaid automatically renders them as rectangles.
  • ((Internet)) uses double parentheses to create a circle shape, which works well for external network boundaries.
  • --> creates a directed arrow between two nodes. Use --- for an undirected link.

This basic structure covers a surprising range of network layouts. You can represent firewalls, switches, routers, servers, load balancers, VPN tunnels, and cloud boundaries with just a few lines.

How Do You Customize Node Shapes for Different Network Devices?

Mermaid supports several bracket styles that change how nodes appear in the rendered diagram. This matters for network diagrams because different device types traditionally use different shapes.

  • [Firewall] Rectangle (default), good for servers and firewalls
  • (Load Balancer) Rounded rectangle, useful for intermediary devices
  • {Switch} Diamond, often used for decision points or switches
  • ((Internet)) Circle, ideal for external networks or cloud endpoints
  • [/Router/] Parallelogram, works for data flow points
  • [[DB Server]] Subroutine shape, good for database systems
  • [(Database)] Cylinder, the standard shape for databases

Here's an example that uses multiple shapes to represent a realistic network setup:

graph LR
 Internet((Internet)) --> FW[Firewall]
 FW --> LB(Load Balancer)
 LB --> SW{Core Switch}
 SW --> Web1[Web Server 1]
 SW --> Web2[Web Server 2]
 Web1 --> DB[(Database)]
 Web2 --> DB

This produces a left-to-right layout showing traffic flowing from the internet through a firewall, load balancer, and switch, then splitting to two web servers that both connect to a database. It communicates the full architecture in a single glance.

How Do You Add Labels and Descriptions to Network Links?

In real network documentation, the connections between devices carry meaning port numbers, protocols, VLANs, bandwidth. Mermaid lets you label links by adding text between the arrow characters.

graph TD
 Router -->|"VLAN 10 - 1Gbps"| Switch_1
 Router -->|"VLAN 20 - 1Gbps"| Switch_2
 Switch_1 -->|"Port 1-24"| Access_Points
 Switch_2 -->|"Port 1-16"| Servers

Place the label text inside quotes after the pipe character |. This keeps your diagrams informative without cluttering the visual layout. If your diagram will be viewed by people who need to understand specific network details, labeled links are essential.

Can You Use Mermaid for Multi-Tier or Layered Network Architectures?

Yes, and this is where Mermaid becomes especially useful for enterprise-style documentation. Multi-tier networks like a classic three-tier architecture with core, distribution, and access layers translate naturally into Mermaid's graph structure.

graph TD
 subgraph Core_Layer [Core Layer]
 Core_Switch_1[Core Switch 1]
 Core_Switch_2[Core Switch 2]
 end

 subgraph Distribution_Layer [Distribution Layer]
 Dist_Switch_1[Dist Switch 1]
 Dist_Switch_2[Dist Switch 2]
 end

 subgraph Access_Layer [Access Layer]
 Access_1[Access Switch 1]
 Access_2[Access Switch 2]
 Access_3[Access Switch 3]
 end

 Core_Switch_1 --- Core_Switch_2
 Core_Switch_1 --> Dist_Switch_1
 Core_Switch_2 --> Dist_Switch_2
 Dist_Switch_1 --> Access_1
 Dist_Switch_1 --> Access_2
 Dist_Switch_2 --> Access_3

The subgraph keyword groups related devices into labeled visual regions. This mirrors how network engineers think about layered infrastructure and makes the diagram much easier to read at scale.

What About Diagramming Cloud or Hybrid Network Topologies?

Cloud network diagrams are one of the most common use cases. Whether you're mapping an AWS VPC, an Azure virtual network, or a hybrid on-premises-to-cloud setup, Mermaid handles it well.

graph LR
 subgraph On-Premises
 FW[Corporate Firewall]
 DC[Data Center Switch]
 end

 subgraph AWS_Cloud [AWS Cloud]
 VPC[VPC - 10.0.0.0/16]
 Pub_Sub[Public Subnet]
 Priv_Sub[Private Subnet]
 IGW[Internet Gateway]
 end

 FW -->|Site-to-Site VPN| VPC
 VPC --> Pub_Sub
 VPC --> Priv_Sub
 IGW --> Pub_Sub
 Pub_Sub --> Web[Web Tier]
 Priv_Sub --> App[App Tier]
 App --> RDS[(RDS Database)]

Using subgraphs to separate on-premises and cloud environments makes the boundary clear. Labels on links can document VPN tunnels, CIDR blocks, and connectivity methods. This is far faster than building the same diagram in a visual tool, and it's easier to maintain when your cloud architecture changes.

How Do You Style Network Diagram Nodes with Colors and Classes?

Mermaid supports classDef and class statements that let you apply CSS-style formatting to nodes. This is useful for color-coding device types in your network diagram.

graph TD
 classDef firewall fill:#ff6666,stroke:#333,color:#fff
 classDef switch fill:#6699ff,stroke:#333,color:#fff
 classDef server fill:#66cc66,stroke:#333,color:#fff

 Internet((Internet)) --> FW[Firewall]:::firewall
 FW --> SW1[Switch 1]:::switch
 FW --> SW2[Switch 2]:::switch
 SW1 --> S1[App Server]:::server
 SW2 --> S2[DB Server]:::server

Each classDef line defines a style with a name, fill color, border color, and text color. Then you apply it to nodes using :::classname at the end of the node definition. Red for firewalls, blue for switches, green for servers whatever color scheme your team prefers.

For teams working on Cisco network topology diagrams with code-based approaches, this color coding mirrors the conventions used in vendor documentation and makes diagrams instantly recognizable.

What Are the Most Common Mistakes When Creating Mermaid Network Diagrams?

After working with Mermaid for network documentation, here are the errors I see most often:

  1. Using spaces in node IDs. Node identifiers like Web Server 1 will break parsing. Use underscores or camelCase: Web_Server_1 or webServer1. You can display a different label by adding text in brackets.
  2. Forgetting arrow direction. A --> B means traffic flows from A to B. Mixing up direction in network diagrams can confuse readers about how data actually moves through your infrastructure.
  3. Overcrowding a single diagram. If your network has 40+ nodes, split it into multiple diagrams by zone, VLAN, or function. A massive diagram with tangled lines helps nobody.
  4. Not using subgraphs. Without grouping, a Mermaid diagram is just a flat list of connections. Subgraphs add the structural context that network diagrams need.
  5. Skipping link labels. Unlabeled connections leave readers guessing about protocols, bandwidths, or VLAN assignments. Add at least the most important details.

Where Can You Render and Share Mermaid Network Diagrams?

You have several options for rendering your Mermaid code into visual diagrams:

  • Mermaid Live Editor The official browser-based editor with live preview. Great for quick drafts and sharing with a URL.
  • GitHub and GitLab Both platforms render Mermaid code blocks directly in markdown files. Just wrap your code in ```mermaid fences.
  • VS Code extensions The "Mermaid Chart" extension previews diagrams inside your editor.
  • Notion Supports Mermaid blocks natively for embedding in documentation pages.
  • Mermaid CLI The @mermaid-js/mermaid-cli npm package generates SVG or PNG files from Mermaid source files, useful for CI/CD pipelines and automated documentation.

If you need more interactive or animated output for presentations, take a look at how to build animated interactive network diagrams with JavaScript that go beyond static rendering.

When Should You Choose Mermaid Over Traditional Diagramming Tools?

Mermaid works best when:

  • Your diagram needs to live alongside code or documentation in a version control system.
  • Multiple people contribute to or update the same diagram over time.
  • You need fast iteration changing a connection or node should take seconds.
  • The audience is technical and doesn't need pixel-perfect visual polish.
  • You want to generate diagrams automatically as part of a documentation build process.

Mermaid is not the right choice when you need precise layout control, complex custom shapes, or publication-quality graphics. For enterprise environments that require specific stencil libraries or vendor-branded diagrams, tools like Visio with network diagram stencils for enterprise infrastructure may be a better fit.

How Do You Handle Large-Scale Network Diagrams in Mermaid?

As your network grows, a single Mermaid diagram becomes hard to manage. Here are practical approaches for scaling up:

  • Split by network zone: Create separate diagrams for the DMZ, internal network, WAN, and cloud environments. Link to each from a master document.
  • Use consistent naming conventions: Prefix node IDs with the zone or function, like dmz_fw, core_sw1, or cloud_lb.
  • Limit subgraph nesting: Mermaid supports nested subgraphs, but deeply nested ones can produce confusing layouts. Keep it to two levels at most.
  • Test rendering frequently: Complex diagrams sometimes produce unexpected layouts. Render after every few additions rather than writing 100 lines before checking.

Quick-Start Checklist for Your First Mermaid Network Diagram

  1. Open the Mermaid Live Editor in your browser.
  2. Start with graph TD (top-down) or graph LR (left-to-right) depending on your layout preference.
  3. List your network devices as nodes use descriptive IDs like Core_Switch, not A or Node1.
  4. Connect devices with --> arrows and add labels with |"label text"|.
  5. Group related devices into subgraph blocks with descriptive names.
  6. Apply classDef styles to color-code device types (firewalls, switches, servers).
  7. Render the preview, fix any parsing errors, and adjust layout direction if the diagram looks cluttered.
  8. Save the Mermaid source in your documentation repo alongside the rest of your infrastructure docs.

Start with a small section of your network even just five devices and their connections. Once the syntax feels natural, expanding to larger diagrams becomes straightforward. The real value shows up months later when you need to update the diagram and you can do it in a text editor in under a minute.