Published on 2026-02-22

BlockDiag Diagrams in Markdown

A Python-inspired syntax for generating clean block and packet diagrams.

BlockDiag is a declarative text-to-image generator that heavily relies on a syntax identical to Graphviz’s DOT language, but it focuses exclusively on block diagrams. It handles the layout algorithm slightly differently than Graphviz, often resulting in more structured, grid-like enterprise architecture charts.

To use it in MarkdownToPrettyPDF, wrap your syntax in a blockdiag code block.

Basic Syntax

Block diagrams are declared simply by pointing nodes at each other using ->. By default, the layout engine arranges them left-to-right or top-to-bottom.

syntax

blockdiag {
  A -> B -> C -> D;
  A -> E -> F -> G;
}

Attributes and Styling

You can assign properties to nodes, such as color, shape, and labels, exactly like you do in DOT/Graphviz.

syntax

blockdiag {
  // Global attributes
  node_width = 120;
  node_height = 40;
  default_fontsize = 14;

  // Node attributes
  A [color = "red"];
  B [label = "Click Here", shape = "roundedbox"];
  C [color = "blue", textcolor="white"];

  A -> B -> C;
}

Grouping

Grouping nodes into clusters is often necessary when drawing system boundaries or network partitions (like “Frontend”, “Backend”, “AWS VPC”).

syntax

blockdiag {
  A -> B -> C;

  group {
    // Group properties
    label = "Backend Cluster";
    color = "#F0F0FF";

    B;
    C;
  }
}

Advanced Shapes

BlockDiag supports numerous built-in shapes to represent servers, databases, actors, and network components:

box
roundedbox
circle
ellipse
actor (A stick figure)
cloud (Often used for the Internet)
flowpan (A database cylinder)

syntax

blockdiag {
  User [shape = "actor"];
  Internet [shape = "cloud"];
  Database [shape = "flowpan"];

  User -> Internet -> Database;
}

When to use BlockDiag?

Use BlockDiag when Graphviz’s auto-layout feels too chaotic or unpredictable. BlockDiag strongly adheres to a neat grid system, which forces your architecture diagrams to look perfectly aligned without manual tweaking.