Railroad EBNF
Last updated:
The EBNF notation (railroad-ebnf-beta) draws a railroad diagram from an Extended Backus-Naur Form grammar.
Among the railroad notations, it is the one Mermaid Studio parses with a dedicated grammar, so rule names resolve as symbols and editing an EBNF diagram feels like editing code.
IDE Support
Section titled “IDE Support”The summary below shows the editor support the EBNF notation ships with, grouped by capability.
Folding lets you collapse and expand structural blocks of the diagram source (subgraphs, frontmatter, multi-line strings) directly in the editor gutter. It keeps long diagrams navigable without forcing you to scroll past detail you don’t need right now.
Use the gutter triangles, Code → Folding, or the standard JetBrains shortcuts (
When the cursor sits next to a bracket, brace, or paren, Mermaid Studio highlights its matching pair across the whole diagram and lets you jump between them. This is especially valuable in nested syntax (subgraph blocks, JSON-style style strings, multi-shape labels) where it’s easy to lose track of which closer goes with which opener.
The line-comment action (
When you type a quote character to start a string, Mermaid Studio inserts the matching closing quote and places the cursor between them. Backspacing through an empty pair removes both characters at once. This keeps quoted labels balanced and reduces fiddly cursor work.
A dedicated Grammar-Kit parser backs the highlighting, so tokens are colored by what they mean in the diagram (a type reference versus a label versus a style), not just what they look like. The same parser validates the syntax as you type, flagging malformed statements in place instead of letting one mistake cascade through the file.
This is the foundation richer features build on; the same grammar drives completions, refactoring, and inspections.
Per-diagram annotators apply rule-based highlighting above the lexer and parser, running on every keystroke and painting their results directly in the editor. Mermaid Studio uses them across the full range the platform supports: highlighting that token types alone cannot decide (coloring a reference by what it resolves to), semantic errors and warnings (an edge pointing at an undefined node, an invalid direction value), and inline cues such as marking duplicate labels. Unlike inspections (configurable checks listed in Settings), annotators are always on, whether a rule ends in a color or a warning.
Completion and validation for the YAML frontmatter block above the diagram body, driven by the diagram type’s slice of the Mermaid config schema. Config keys, enum values, and color properties complete as you type, and unknown or mistyped keys are flagged in place.
A dedicated page under Settings → Editor → Color Scheme for the diagram type, listing every highlighting attribute its parser produces with a live preview. This is what makes the difference between “the theme colors it somehow” and “you decide exactly how keywords, identifiers, labels, and styles render”.
Rename refactoring (
Find Usages (
Rule references resolve to their declarations, so find usages, Go to Declaration, and rename (/* */, ISO (* *), and Mermaid %% lines), and a parse error in one rule stays in that rule instead of cascading through the file.
Live preview
Section titled “Live preview”An EBNF diagram opens in a split editor with the highlighted grammar on the left and the rendered railroad tracks on the right, both following your IDE theme. Because the dedicated grammar colors by role, each rule name carries the declaration color where it is defined and the reference color where another rule uses it, so the shape of the grammar reads at a glance.
Quick Syntax Reference
Section titled “Quick Syntax Reference”An EBNF diagram opens with the railroad-ebnf-beta keyword and optional meta statements, then declares one rule per statement, each ending with a semicolon.
The example below defines a small JSON grammar:
railroad-ebnf-betatitle "JSON Grammar"
json = element ;element = object | array | string | number | "true" | "false" | "null" ;object = "{" [ member ( "," member )* ] "}" ;member = string ":" element ;Key elements:
- A rule assigns a name with
=or the ISO::=form and ends with; |separates alternatives,( )groups,[ ]marks an optional part, and{ }marks repetition- The postfix quantifiers
?,*, and+work on any term, and the ISO exception operator-excludes a match - Terminals are quoted strings;
? free text ?marks a special sequence - Comments come in three styles: W3C
/* */, ISO(* *), and Mermaid%%line comments title,accTitle, andaccDescrstatements must appear before the first rule
For complete syntax details, see the Mermaid railroad documentation.