EBNF Grammar Diagrams: Turning a Formal Grammar into a Readable Derivation Chart

Introduction

EBNF is the standard notation for describing the syntax of a formal language: rule after rule, written with great precision — and read like a wall of symbols. In expr = term , { ( "+" | "-" ) , term } ; the comma means concatenation, { } means zero-or-more, parentheses mean grouping and | means alternation, and each symbol drives the derivation in a different way.

Drawing the grammar as a diagram makes the layering, the loops and the branches immediately visible. PlantUML ships an @startebnf engine that consumes plain EBNF text and produces the derivation diagram for you. Mermaid has no grammar engine, but a flowchart with the right nodes and loop-back edges reproduces exactly the same structure by hand. The example below uses a small arithmetic expression grammar.

PlantUML version

@startebnf is essentially EBNF itself: one production per line, = introduces the left-hand symbol and the right-hand side is its expansion, and a trailing semicolon closes the rule. Here is the complete expression grammar:

1
2
3
4
5
6
7
8

@startebnf
title Mini expression grammar
expr = term , { ( "+" | "-" ) , term } ;
term = factor , { ( "*" | "/" ) , factor } ;
factor = number | "(" , expr , ")" ;
number = digit , { digit } ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
@endebnf

The result is a top-down derivation diagram: expr at the top, then term, factor, number and digit below it. The { } becomes a loop-back arrow meaning zero-or-more, | becomes a fork, and the edge from factor to "(" , expr , ")" is the recursion — a parenthesised expression is itself an expr.

A few notation traps to keep in mind: the comma in front of { } is a concatenation operator and cannot be dropped; | needs surrounding spaces ("+" | "-" rather than "+"|"-"); ? is the special-sequence marker and * is the repetition marker, both PlantUML extensions rather than standard EBNF. To annotate a rule, put a (* ... *) comment right after the element it describes.

Mermaid version

Mermaid has no grammar engine, so each production has to be translated into nodes: a diamond decides “repeat or stop”, a loop-back edge stands for { }, and two outgoing edges stand for the two branches of |.

1
2
3
4
5
6
7
8
9
10
11
12

flowchart TD
  EXPR["expr"] --> TERM["term"]
  TERM --> TOP{"repeat ( '+' | '-' ) term"}
  TOP -->|yes| TERM
  TOP -->|no| FACTOR["factor"]
  FACTOR --> NUMBER["number"]
  FACTOR --> PAREN["'(' expr ')'"]
  PAREN --> EXPR
  NUMBER --> DIGIT["digit"]
  DIGIT --> DREP{"repeat digit"}
  DREP -->|yes| DIGIT
  DREP -->|no| FIN(["end of expr"])

Read it side by side with the grammar: the diamond under TERM is the brace group in term = factor , { ( "*" | "/" ) , factor } — the yes edge loops back to TERM itself and the no edge continues downward, which is exactly the “repeat or terminate” semantics. The two outgoing edges of FACTOR correspond to the two productions number and "(" , expr , ")", and PAREN points back at EXPR to draw the recursion.

Two practical notes for Mermaid: put special characters inside double quotes, and quote the parentheses inside node labels as well. Also note that end is a flowchart keyword in Mermaid — using it as a node id makes the render fail — which is why the terminal node above is named FIN.

Side-by-side

Wrap-up

@startebnf means “hand the grammar to the engine”: standard EBNF goes in, a proper derivation diagram comes out, which is ideal for language specifications and design reviews. A Mermaid flowchart means “translate the grammar into a diagram”: more work, but you can add prose, colours and domain explanations wherever you need them. A practical workflow is to generate the skeleton with PlantUML first, confirm the rules are right, and only then decide whether the audience needs a friendlier Mermaid version on top.