Mermaid block-beta examples for layers and grids

These mermaid block-beta examples are grids you type by hand: a column count, a block written as id["Label"], and an arrow only where the row order would otherwise lie. I use them when the rows themselves mean something, such as tiers of a system or stages of a pipeline sitting side by side. A flowchart will reshuffle those boxes the moment you add an edge. A block diagram will not, which is the whole feature and also the way you can ship a confusing layout with confidence.

The keyword is block-beta. It is still a beta diagram type, so a host that renders flowcharts can reject the file. The block diagram syntax page is the reference I keep open while I edit. This page is a set of grids I would actually commit, plus the column behavior that makes them wrap when you did not mean to wrap.

What a column count decides

columns 1 means one block per row. The next line is the next row down. That is the layout. You are not describing a graph and hoping the renderer shares your taste. columns 3 fills a row left to right and then wraps. Four blocks with columns 3 put three on the first row and one alone on the second. The orphan is not a styling bug. It is the column count doing arithmetic.

I start at columns 1 until the stack reads in the order I want, then I widen. Widening too early is how a database ends up beside a button with an arrow that has to explain the accident. Ids stay short and stable. The label inside the quotes is what the reader sees. api["Public API"] can change to api["Billing API"] without touching a single arrow, as long as the id api remains. I have "fixed" a label by renaming the id, left the arrows on the old id, and stared at a parse error that was entirely earned.

Labels are names, not sentences. The cell is small. A protocol, a port, or a warning belongs in the paragraph under the figure, or on an arrow if the neighbor is ambiguous. Spans, the syntax that lets one block cover several columns, are real and easy to get half-right. I am not teaching span here. A wrong span is a hole in the grid, and the syntax page is the place to copy a known-good one. Every example below is columns, quoted labels, and plain --> arrows.

Three tiers in one column

A small app is three layers. The page sits on top, the API in the middle, the database at the bottom. One column makes "on top" a fact instead of a wish.

block-beta
columns 1
web["Web"]
api["API"]
db["Database"]
web --> api
api --> db

columns 1 is the layout decision. Web cannot drift beside the API, because there is no beside. The arrows repeat what the stack already says, and I still add them when a reader might think the page talks to the database directly. If your real system lets the page do that, the stack is now a lie. Add web --> db or stop using a single column and draw the call you actually have.

Order is list order. A cache inserted at the bottom of the file lands under the database, which is probably wrong. Put the cache line where the layer sits. With one column there is nowhere else for it to go, which is why this form is kind to the author and rude to anything that is not a stack.

This picture will not show request order. It shows arrangement. Pair it with a sequence diagram when the question is who calls whom during one checkout. Leave this file as the map of tiers. A reader should point at a row and name the tier. If they cannot, the column count is hiding the story you thought you wrote.

The system layers template is a wider version of this stack, with more than one box in a tier. Start there when you already know you need a row of clients over a row of services. Start with the three lines above when you are still arguing about which tier exists.

A CI row that should not wrap

A pipeline is a row. Lint, test, build, and ship belong beside each other because "beside" means "then" for this picture. Four names, so columns 4.

block-beta
columns 4
lint["Lint"]
test["Test"]
build["Build"]
ship["Ship"]
lint --> test
test --> build
build --> ship

The arrows are the order. The columns are the promise that those four boxes share a row. If I had used columns 3, Ship would wrap under Lint and the picture would claim a second line of work. I have presented that wrap in a design review and called it "the layout engine." It was my column count. The reviewer was right to look confused.

Skip arrows when the row is obvious and you are short on space. I keep them on a pipeline because a reader from outside the team will not assume left-to-right means time. On the tier stack above, top-to-bottom already means dependency for most engineers, so the arrows are optional. On a row of job names, I want the arrow. Taste is allowed. Lying about order is not.

Job names should match the CI config. "Build" is a weak label if the workflow file says image. Use the name people grep for. A block diagram that invents friendlier words becomes a second glossary, and the glossary will lose.

Two columns when the split is the point

Some pictures are a pair. The author produces a change, the reviewer accepts or sends it back. Two columns put those roles side by side. Stacking them would imply that review is a lower tier of the same system, which is a different claim.

block-beta
columns 2
author["Author"]
reviewer["Reviewer"]
draft["Draft"]
notes["Notes"]
author --> draft
reviewer --> notes
draft --> reviewer

Read the fill order before you trust the picture. columns 2 places Author and Reviewer on the first row, then Draft and Notes on the second. Author sits over Draft. Reviewer sits over Notes. The arrow from Draft to Reviewer is the handoff. I added it because the grid alone says "these are columns," and the handoff is the only part that is not a column fact.

If you wanted Draft under Author and nothing else on that row, you do not want a fourth block yet. Two blocks and columns 2 is a single row. A third block wraps. Count the blocks, then set the columns, then look. I still get this wrong when I paste an extra idea at the end of the file and forget that paste is a layout change.

A decision can use the same shape. Question on the left, outcome on the right, as long as you accept that block diagrams do not have diamonds. If the yes and the no are the story, a flowchart is the honest tool. I use two columns here for roles and work products, where the geometry is "these sit together," and the prose says what "together" means.

A wrap I would rather see than discover

Three columns and four blocks is the mistake I want on the page once, so you recognize it in your own file. Web, API, and Worker share the first row. Database sits alone on the second, looking like a footer.

block-beta
columns 3
web["Web"]
api["API"]
worker["Worker"]
db["Database"]
api --> db

That lonely database might be what you wanted, a full-width idea that you faked by leaving the row short. It might also be an accident. Block-beta will not ask. If the database should span the row, this is the moment to go read span syntax on the block diagram syntax page, or to switch to columns 1 and stack the tiers, or to use columns 4 and accept a gap only if you meant a gap. I pick the stack when the story is layers. I pick four columns when the story is four peers. I do not leave the orphan and hope the caption saves me.

The arrow api --> db still works after the wrap. Arrows do not change the grid. They draw on top of it. A diagram full of arrows between every pair hides the columns you just set. Add an arrow where the neighbor is not obvious from the row or the stack, and stop.

Ids, quotes, and the words that break the file

The id is on the left of the brackets. The label is inside the quotes. worker["Worker"] is a block. Worker["worker"] is a different block, and any arrow aimed at worker now hits nothing. I keep ids lowercase and labels in the team's words.

Quotes matter when the label contains parentheses, a colon, or anything the parser could read as syntax. api["API (public)"] is the safe form. api[API (public)] is how a label becomes a puzzle. I quote every block label in these examples, including the dull ones, so the file has one pattern. Consistency is cheaper than remembering which characters are special on a Friday.

Do not name a block end. That word closes regions in other diagram types, and it is a bad id here even when the file happens to render. done or finish carries the same meaning. Do not name a block columns either. You will confuse the next editor, and you might confuse yourself when you grep the file.

Beta means a Markdown host can show the source instead of the grid. If GitHub or Notion gives you a code block or a parse error, the grid is not wrong just because that host is behind. Check the same text in a renderer that knows block-beta. If it fails there too, the column line or a missing quote is the usual cause. The cheat sheet has the block line in short form when you do not want this whole page open.

When a flowchart or a cloud picture is the better file

Use a flowchart when the boxes are decisions and you want automatic layout. Use an architecture diagram when the boxes should be cloud icons inside a network group. The schematic diagram creator and the text to schematic diagram notes sit closer to "draw the components" than this page does. A block grid is the narrower tool: rows and columns with meaning. If I cannot say what a row means in four words, I have the wrong diagram type and more arrows will not repair it.

AWS-shaped pictures are a common temptation. People want the official icons and a VPC box. A block diagram will give you rectangles in a grid, which is fine for a tier discussion and wrong for a security review that expects the vendor's shapes. The Mermaid AWS diagrams post is the place to settle that expectation. I keep the block file for the layout we agreed, and I refuse to maintain a fake icon set inside labels like "[S3]" pretending to be a product diagram.

The block diagram generator is the tool-shaped version of this conversation. Generating a first grid from a sentence is reasonable. You still set columns yourself after you see the wrap. A generated file that puts the database beside the browser has picked a column count, not a truth. Change the number, move the lines, look again.

Edit the number, then the words

I edit column count before I edit adjectives. A wrong columns value makes every label look bad, and rewriting labels will not put Ship back on the first row. Change the number, preview, and only then rename build["Build"] to the job name in the workflow file.

Open the editor with one of the grids above. The free editor needs no signup, and the preview is live, so the wrap shows up on the keystroke that caused it. When you want a first draft from a sentence instead of from a blank file, the AI block diagram generator will emit block-beta you can correct. It can also edit or fix a grid you paste in. Free accounts include 5 AI uses in total, so spend them after you know whether you wanted a stack or a row. The column count is the part I still do not trust a sentence to decide.