← All diagram types

Mermaid block diagram syntax: columns, spans and sub-grids with examples

Mermaid block-beta syntax with rendered examples: column counts, column spans, space gaps, nested sub-grids, node shapes and labelled edges.

A block diagram places boxes on a grid you lay out yourself: no automatic graph layout, no edges deciding the shape. It is the diagram type for architectures and layer stacks where the position of each block is the point.

Everything on this page is rendered by makesPDF's own Mermaid renderer, so a ```mermaid block produces exactly this in the PDF.

Columns

columns N fixes the grid width, and the blocks that follow flow left to right, wrapping into new rows. Without it the whole diagram is a single row:

mermaid
block-beta
  columns 3
  Frontend API Auth
  Renderer Queue Storage
Render this to PDF →How diagram blocks work

Each bare name is a block with the same label. Spacing in the source does not matter — the column count does.

Labels and shapes

id["Label"] gives a block a separate display label, and the bracket style picks its shape, using the same set as a flowchart: ["rect"], ("rounded"), (["stadium"]), [("database")], {{"hexagon"}}, {"diamond"}, (("circle")):

mermaid
block-beta
  columns 3
  ui["Web UI"]
  api("API")
  db[("Postgres")]
Render this to PDF →How diagram blocks work

Spans and spaces

id:N makes a block span N columns. A bare space (or space:2) leaves a gap, which is how a sidebar or a centred row is built:

mermaid
block-beta
  columns 4
  header["Header"]:4
  nav["Nav"] body["Content"]:3
  footer["Footer"]:4
Render this to PDF →How diagram blocks work

The middle row has nav in one column and body spanning the other three; the header and footer take the full width.

Sub-grids

block:id:N … end opens a composite block with its own columns and its own layout. It is addressable by id, so edges can point at the group as a whole:

mermaid
block-beta
  columns 2
  client["Client"]
  block:services:2
    columns 2
    api["API"] workers["Workers"]
  end
  client --> services
Render this to PDF →How diagram blocks work

A composite block can nest further, and its internal columns are independent of the outer grid.

Edges

Arrows connect blocks by id: A --> B for an arrow, A --- B for a plain line, and A -- "label" --> B to name the connection:

mermaid
block-beta
  columns 4
  browser["Browser"] space space origin["Origin"]
  space cdn["CDN"] space space
  browser --> cdn
  browser -- "cache miss" --> origin
  cdn --- origin
Render this to PDF →How diagram blocks work

Edges are drawn as straight connectors between block edges, so placement is what decides the routing — a block diagram is not auto-laid out. The blocks on either end must already be declared, and an edge line holds nothing but the two ids and the optional label.

Not supported in makesPDF yet: block arrows (id<["label"]>(right)) are drawn as plain rectangles with the direction ignored, and an unrecognised shape falls back to a rectangle. style, classDef and class lines are accepted but not painted, so every block uses the theme's fill.