Mermaid.js Packet Diagram: Visualize Network Protocols with Text

# Mermaid.js Packet Diagram: Visualize Network Protocols with Text

Mermaid.js v11 introduced a new diagram type that's quietly become essential for anyone documenting network systems: the packet diagram. It renders binary protocol frames — TCP headers, HTTP frames, DNS packets, custom binary formats — directly from text. No Wireshark screenshot, no Visio template, no pixel pushing.

If you've ever tried to document a network protocol in a README and ended up with a badly-formatted ASCII table, this guide is for you.

What Is a Mermaid Packet Diagram?

A packet diagram visualizes how a binary message is laid out in memory or on the wire. Each field gets a labeled block showing its bit width. Classic use cases:

- TCP/IP header documentation

- Custom binary protocol specs

- Ethernet frame layouts

- DNS or HTTP/2 frame structures

- Embedded systems message formats

- IoT device communication protocols

The output looks like the RFC-style packet diagrams you've seen in networking textbooks — but it's generated entirely from plain text.

Basic Syntax

Every packet diagram starts with the packet-beta keyword:

packet-beta
  0-7: "Version"
  8-15: "IHL"
  16-31: "Total Length"

Each line follows the pattern -: "Field Name". Bit ranges are inclusive and zero-indexed. Mermaid lays the fields out left-to-right, wrapping to the next row at 32 bits by default (one 32-bit word per row).

For a single-bit field, the start and end are the same number:

packet-beta
  0-3: "Version"
  4: "SYN"
  5: "ACK"
  6: "FIN"
  7-15: "Reserved"

Real Example: IPv4 Header

Here's the complete IPv4 header — 20 bytes (160 bits):

packet-beta
  0-3: "Version"
  4-7: "IHL"
  8-15: "DSCP+ECN"
  16-31: "Total Length"
  32-47: "Identification"
  48-50: "Flags"
  51-63: "Fragment Offset"
  64-71: "TTL"
  72-79: "Protocol"
  80-95: "Header Checksum"
  96-127: "Source IP Address"
  128-159: "Destination IP Address"

That's 20 bytes, laid out across 5 rows of 32 bits each, exactly matching the IPv4 RFC diagram. 12 lines of text instead of a 200px imported image that goes stale.

TCP Header

TCP has a richer header with control flags — perfect for showing how Mermaid handles both wide fields and individual bits:

packet-beta
  0-15: "Source Port"
  16-31: "Destination Port"
  32-63: "Sequence Number"
  64-95: "Acknowledgment Number"
  96-99: "Data Offset"
  100-105: "Reserved"
  106: "URG"
  107: "ACK"
  108: "PSH"
  109: "RST"
  110: "SYN"
  111: "FIN"
  112-127: "Window Size"
  128-143: "Checksum"
  144-159: "Urgent Pointer"

The single-bit flag fields (URG, ACK, PSH, RST, SYN, FIN) each get their own narrow column. Wider fields like Source Port span multiple columns proportionally — exactly what you want in protocol documentation.

DNS Query Header

Here's how a DNS query header looks:

packet-beta
  0-15: "Transaction ID"
  16: "QR"
  17-20: "Opcode"
  21: "AA"
  22: "TC"
  23: "RD"
  24: "RA"
  25-27: "Z"
  28-31: "RCODE"
  32-47: "QDCOUNT"
  48-63: "ANCOUNT"
  64-79: "NSCOUNT"
  80-95: "ARCOUNT"

The Z (reserved) field correctly spans bits 25-27. This is exactly the kind of detail that's painful to draw but trivial to write.

Custom Binary Protocol

Packet diagrams aren't just for standard networking protocols. They're equally useful for custom binary formats — IoT messages, game packets, embedded systems:

packet-beta
  0-7: "Magic Byte"
  8-15: "Version"
  16-23: "Type"
  24-31: "Flags"
  32-63: "Timestamp (Unix)"
  64-95: "Device ID"
  96-127: "Payload Length"
  128-191: "Payload (variable)"
  192-223: "CRC-32"

This kind of diagram is invaluable in embedded firmware docs where every byte counts and the binary layout needs to be unambiguous.

HTTP/2 Frame Header

Modern protocols like HTTP/2 use binary framing. Here's the HTTP/2 frame header:

packet-beta
  0-23: "Length (24 bits)"
  24-31: "Type"
  32-39: "Flags"
  40: "R"
  41-71: "Stream Identifier (31 bits)"

The reserved R bit gets its own 1-bit cell, and the stream identifier correctly shows as 31 bits — nuances that matter when you're building an HTTP/2 implementation.

Packet Diagrams vs Other Mermaid Types

Tips for Clean Packet Diagrams

Match bit ranges to real specs. Off-by-one errors render fine but document the wrong layout — always cross-check against the RFC.

Use the spec's exact field names. Your teammates will cross-reference the diagram against the standard.

Order fields by bit position. Write them top-to-bottom in bit order, not alphabetical order.

Explain semantics in prose. The diagram shows *what* the layout is. A paragraph explains *why* each field exists and what values mean.

Version Requirement

Packet diagrams require Mermaid v11 or newer:

• GitHub — renders packet-beta as of late 2024
• mermaideditor.lol — fully supported ✓
• VS Code Mermaid plugin — update to latest version
• Self-hosted — bump your CDN/npm to ^11

Conclusion

Mermaid packet diagrams fill a gap that no other diagram type covered: binary protocol visualization as code. Whether you're writing a networking tutorial, speccing a custom IoT protocol, or reviewing firmware, packet diagrams give you RFC-quality layouts from a dozen lines of text.

Like all Mermaid diagrams, they live in your repo, diff cleanly in PRs, and never drift out of sync the way exported images do.

Try the Mermaid packet diagram editor — paste any example and see it render instantly →