Railroad Diagram
Last updated:
Mermaid Studio recognizes and renders railroad syntax diagrams inside IntelliJ IDEA and other JetBrains IDEs. Railroad diagrams, also called syntax diagrams, draw a formal grammar as a set of tracks so you can trace every valid path through a production left to right. Mermaid Studio recognizes all four notations the upstream renderer supports: an internal-representation (IR) form built from explicit primitives, plus the EBNF, ABNF, and PEG grammar notations.
Live Preview
Section titled “Live Preview”Mermaid Studio opens a railroad diagram in a split editor with the highlighted source on the left and the rendered tracks on the right, and the preview theme and background follow your IDE. The example below shows the same grammar rendered under three IDE themes.
Notations
Section titled “Notations”Mermaid Studio recognizes four railroad notations, each selected by its own diagram-type keyword on the first line. Pick the notation that matches the grammar you already have:
| Notation | Keyword | Use it for |
|---|---|---|
| IR primitives | railroad-beta | Composing diagrams from explicit sequence, choice, and repetition primitives |
| EBNF | railroad-ebnf-beta | Extended Backus-Naur Form grammars with |, [ ], and ( )* |
| ABNF | railroad-abnf-beta | Augmented Backus-Naur Form grammars with /, *( ), and core rules |
| PEG | railroad-peg-beta | Parsing Expression Grammars with <-, ordered choice, and +/* quantifiers |
The four notations share a single frontmatter config schema. The EBNF notation additionally has a dedicated grammar with language intelligence (semantic highlighting, syntax validation, rule rename, find usages); see Railroad EBNF.
IDE Support
Section titled “IDE Support”The IR, ABNF, and PEG notations share a generic diagram-language base that covers the editing basics: basic syntax highlighting, brace matching, quote handling, and code folding. The EBNF notation goes further with a dedicated grammar; its editor features are covered on the Railroad EBNF page.
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.
The editor colors the diagram source with a lexer that understands the diagram type: keywords, identifiers, strings, numbers, comments, and operators each get their own color scheme attributes. Colors integrate with the IDE’s color scheme, so themes apply automatically.
Diagram types with a dedicated grammar go further; see Semantic Highlighting.
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”.
All four notations are detected from their first-line keyword, offered by the diagram-type completion as you type the opening line, and rendered in the live preview with the theme and background following your IDE.
Frontmatter completion and validation cover the config.railroad keys, with color-aware completion for the fill, stroke, and line-color options.
The notations work in .mmd and .mermaid files and inside mermaid fenced code blocks in Markdown alike, and the preview links to the upstream Mermaid railroad reference.
Highlighting for the IR, ABNF, and PEG notations is token-based rather than grammar-backed, so the editor does not validate the diagram body or resolve rule names; a status bar indicator marks these files, as covered on the Basic Syntax Highlighting page. Diagram-body completion, formatting, refactoring, structure view, and find usages likewise require a dedicated grammar, which among the railroad notations only EBNF has.
Quick Syntax Reference
Section titled “Quick Syntax Reference”The IR notation builds a diagram by nesting primitive functions such as sequence, choice, zeroOrMore, oneOrMore, terminal, and nonterminal.
Each rule assigns a name to one of these expressions and ends with a semicolon:
railroad-betatitle Expression Grammar
term = sequence( nonterminal("factor"), zeroOrMore(sequence( choice(terminal("*"), terminal("/")), nonterminal("factor") ))) ;The EBNF notation uses Extended Backus-Naur Form, where | separates alternatives, [ ] marks an optional group, and ( )* marks repetition.
Terminals are quoted strings.
EBNF is the one railroad notation with dedicated language support in the editor:
railroad-ebnf-betatitle "JSON Grammar"
json = element ;element = object | array | string | number | "true" | "false" | "null" ;object = "{" [ member ( "," member )* ] "}" ;array = "[" [ element ( "," element )* ] "]" ;member = string ":" element ;The ABNF notation uses Augmented Backus-Naur Form, where / separates alternatives, *( ) marks repetition, and 1*( ) requires at least one occurrence.
Core rules such as ALPHA and DIGIT are available by name:
railroad-abnf-betatitle "Email Address"
address = local-part "@" domain ;local-part = 1*( ALPHA / DIGIT / "." / "-" ) ;domain = label *( "." label ) ;label = 1*( ALPHA / DIGIT / "-" ) ;The PEG notation uses Parsing Expression Grammar syntax, where <- assigns a rule, / is an ordered choice, and +/* are quantifiers.
Ordered choice means the first matching alternative wins:
railroad-peg-betatitle "Calculator Grammar"
Expression <- Term (("+" / "-") Term)* ;Term <- Factor (("*" / "/") Factor)* ;Factor <- Number / "(" Expression ")" ;Number <- Digit+ ;Digit <- "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" ;For complete syntax details across all four notations, see the Mermaid railroad documentation.