How to Draw Block Diagrams in Mermaid

2026-03-05 · MermZen Tutorial

Block diagrams visualize complex system component structures, hierarchical relationships, and connections. They are ideal for system architecture design, network topology, and industrial flow diagrams. Mermaid uses block-beta keyword for block diagrams.

Why Use Block Diagrams?

Block diagrams are essential tools for visualizing complex systems:

• Visualize component structure — See at a glance how components are organized and connected
• Show hierarchical relationships — Clearly display nesting and containment
• System design aid — Plan and document system architecture
• Network topology — Ideal for visualizing network infrastructure

Use Cases

✅ Suitable:

• System architecture design
• Network topology visualization
• Industrial process diagrams
• Module structure planning

❌ Not Suitable:

• Showing time sequence → Use sequence diagram
• Showing decision flow → Use flowchart
• Showing detailed class structure → Use class diagram

Comparison with Other Diagrams

Selection Guide:

• Show "how modules nest" → Block diagram
• Show "what services exist" → Architecture diagram
• Show "what steps to follow" → Flowchart

Declaring a Chart

Use block-beta keyword:

block-beta
    title Block Diagram Title

Basic Block Definition

Create simple blocks and connections:

block-beta
    title Basic Block Diagram
    block "Block A"
    block "Block B"
    block "Block C"

    "Block A" --> "Block B"
    "Block A" --> "Block C"
    "Block B" --> "Block C"

Nested Block Structures

Create complex nested structures with sub-blocks:

block-beta
    title Nested Block Diagram
    block "System" {
        block "Subsystem 1" {
            block "Component A"
            block "Component B"
        }
        block "Subsystem 2" {
            block "Component C"
            block "Component D"
        }
    }

    "Component A" --> "Component C"
    "Component B" --> "Component D"
    "Subsystem 1" --> "Subsystem 2"

Full Example: Network Topology

block-beta
    title Company Network Topology
    block "Headquarters Network" {
        block "Core Switch"
        block "Server Cluster" {
            block "Web Server"
            block "Database Server"
            block "Application Server"
        }
        block "Office Network" {
            block "Employee Computers"
            block "Printers"
        }
    }
    block "Branch Office" {
        block "Branch Switch"
        block "Local Server"
        block "Employee Devices"
    }
    block "Internet"

    "Core Switch" --> "Web Server"
    "Core Switch" --> "Database Server"
    "Core Switch" --> "Application Server"
    "Core Switch" --> "Employee Computers"
    "Core Switch" --> "Printers"
    "Core Switch" --> "Internet"
    "Branch Switch" --> "Local Server"
    "Branch Switch" --> "Employee Devices"
    "Branch Switch" --> "Internet"

Best Practices

Nesting Depth Guidelines

• Recommended depth: 2-4 levels maximum
• Too deep: More than 4 levels becomes hard to read
• Solution: Split into multiple diagrams if needed

Connection Guidelines

• Keep connections simple: Avoid crossing lines
• Group related connections: Connect at the appropriate level
• Limit connections per block: 5 or fewer connections recommended

Naming Conventions

Common Mistakes

Mistake 1: Overly Deep Nesting

❌ Problem: Nesting 5+ levels deep creates unreadable diagrams

✅ Solution: Keep to 2-4 levels, split complex systems into multiple diagrams

Mistake 2: Too Many Connections

❌ Problem: Connecting every block to every other block creates visual clutter

✅ Solution: Only show important relationships, document others separately

Mistake 3: Inconsistent Abstraction Levels

❌ Problem: Mixing high-level concepts with low-level details in same diagram

✅ Solution: Keep all blocks at the same level of abstraction

Quick Reference

Next Step

After mastering block diagrams, continue learning Mermaid Requirement Diagrams for project requirements management and analysis.

To try the above code in MermZen, click Open Editor and paste the code there.