Network topology diagrams with PlantUML and Mermaid

简介 / Introduction

A network topology diagram is one of the most common artifacts in operations and architecture docs: it shows how servers and links are arranged across the public internet, a DMZ, and the core network. This post draws the exact same “internet → DMZ → core” topology twice — first with PlantUML’s nwdiag engine, then with Mermaid’s flowchart plus subgraph — and compares what each engine can express.

PlantUML 版

PlantUML ships with Takeshi Komiya’s nwdiag engine, enabled via @startnwdiag. A network is declared as a network block, and each block can carry a subnet via address. Nodes are declared as id [address = "..."]. Links between networks use --, while nodes inside the same network automatically attach to that network’s bus bar.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

@startnwdiag
title Data Center Topology

group internet_zone {
  color = "#E8F0FE";
  description = "Public Internet";
  internet [shape = cloud, address = "0.0.0.0/0"];
}

network dmz {
  address = "10.0.0.0/24";
  color = "palegreen";
  proxy [address = "10.0.0.10"];
  web [address = "10.0.0.20"];
}

network core {
  address = "10.1.0.0/24";
  app [address = "10.1.0.10"];
  db [address = "10.1.0.20"];
}

internet -- proxy;
proxy -- web;
proxy -- app;
app -- db;
@enduml

A few nwdiag constraints are worth knowing up front: subnet and group names must not be quoted, and a link cannot carry a [label = "..."] attribute (it fails with a Syntax Error). The only accepted arrow form is --.

Mermaid 版

Mermaid has no dedicated topology engine, but flowchart with subgraph reaches the same visual result. A subgraph plays the role of a PlantUML network / group block, IP addresses go inside the node label separated by <br/>, and edge labels use the -->|"text"| form to carry protocol and port.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

flowchart TB
  subgraph EXT["Public Internet"]
    internet["Internet Cloud"]
  end
  subgraph DMZ["DMZ — 10.0.0.0/24"]
    proxy["Reverse Proxy<br/>10.0.0.10"]
    web["Web Server<br/>10.0.0.20"]
  end
  subgraph CORE["Core Network — 10.1.0.0/24"]
    app["App Server<br/>10.1.0.10"]
    db["Database<br/>10.1.0.20"]
  end
  internet -->|"HTTPS :443"| proxy
  proxy -->|"HTTP :80"| web
  proxy -->|"gRPC :9090"| app
  app -->|"SQL :5432"| db

Mermaid subgraph titles can include the subnet directly, and -->|"..."| edge labels have none of the restrictions that nwdiag places on links.

对比 / Side-by-side

小结 / Wrap-up

Both engines can produce a readable network topology, but they optimize for different things. PlantUML’s nwdiag is network-semantics-first: subnets, bus bars, and addresses are built in, which maps cleanly onto a real segmented network. Mermaid’s flowchart is diagram-expression-first: edge labels and node shapes are far more flexible, which makes it a better fit for documentation that mixes topology with other concepts. Keep in mind that nwdiag is stricter than it looks — no quoted subnet names, no labeled links — and when you hit those limits, switching to Mermaid is usually the faster path.