Railroad Diagram

Requires Mermaid 11.16.0+

Railroad syntax diagrams are a Mermaid 11.16.0 feature. The plugin recognizes the language at any runtime, but rendering only works against Mermaid 11.16.0 or newer. Pick the runtime under Settings > Tools > Mermaid Studio > Mermaid Runtime if you’ve pinned an older version.

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.

Beta diagram type

Railroad is a beta diagram type in Mermaid.js, so its syntax, configuration, and rendering may still change as the upstream implementation matures.

Live Preview

Mermaid Studio renders railroad diagrams in the live preview, and the preview theme and background follow your IDE. The example below shows the same railroad diagram rendered under three IDE themes.

Armada Dark

Islands Dark

Islands Light

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 and the same editor support; only the first-line keyword and the rule syntax differ.

IR primitives

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-beta
title Expression Grammar

term = sequence(
    nonterminal("factor"),
    zeroOrMore(sequence(
        choice(terminal("*"), terminal("/")),
        nonterminal("factor")
    ))
) ;

EBNF

The EBNF notation uses Extended Backus-Naur Form, where | separates alternatives, [ ] marks an optional group, and ( )* marks repetition. Terminals are quoted strings:

railroad-ebnf-beta
title "JSON Grammar"

json = element ;
element = object | array | string | number | "true" | "false" | "null" ;
object = "{" [ member ( "," member )* ] "}" ;
array = "[" [ element ( "," element )* ] "]" ;
member = string ":" element ;

ABNF

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-beta
title "Email Address"

address = local-part "@" domain ;
local-part = 1*( ALPHA / DIGIT / "." / "-" ) ;
domain = label *( "." label ) ;
label = 1*( ALPHA / DIGIT / "-" ) ;

PEG

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-beta
title "Calculator Grammar"

Expression <- Term (("+" / "-") Term)* ;
Term <- Factor (("*" / "/") Factor)* ;
Factor <- Number / "(" Expression ")" ;
Number <- Digit+ ;
Digit <- "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" ;

IDE Support

Railroad support centers on detecting the diagram, rendering it, and the metadata around it rather than in-editor language intelligence. All four notations share the same support. Mermaid Studio provides:

• Detection of all four notations from their first-line keyword, so the diagram is recognized and rendered wherever it appears
• Diagram-type keyword completion that offers railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, and railroad-peg-beta as you type the first line
• Live preview rendered by the bundled Mermaid runtime, with the theme and background following your IDE
• Frontmatter config completion and validation for the config.railroad keys, with color-aware completion for the fill, stroke, and line-color options
• Documentation links from the preview to the upstream Mermaid railroad reference
• File recognition for .mmd and .mermaid files, plus injection into mermaid fenced code blocks in Markdown

Railroad does not have semantic syntax highlighting. Diagram-body completion, validation, code folding, formatting, brace matching, refactoring, structure view, and find usages are also not available.

Frontmatter Configuration

Railroad exposes a config.railroad block in the YAML frontmatter, shared by all four notations. Mermaid Studio validates these keys against the railroad config schema, so you get completion and type checking inside the frontmatter, including color-aware completion for the fill and stroke options.

The most commonly adjusted keys are layout and color controls:

Key	Description	Default
compactMode	Use the compact layout	false
fontSize	Font size for text	14
terminalFill	Fill color for terminal elements	"#FFFFC0"
nonTerminalFill	Fill color for non-terminal elements	"#FFFFFF"
lineColor	Color for connection lines	"#000000"
specialFill	Fill color for special sequences	"#F0E0FF"
ruleNameColor	Color for rule names	"#000066"

Set them in the YAML frontmatter above the diagram body:

---
config:
  railroad:
    compactMode: true
    terminalFill: "#e0f2f1"
    nonTerminalFill: "#ffffff"
    lineColor: "#00897b"
---
railroad-beta
term = sequence(nonterminal("factor"), terminal("*")) ;

The schema also covers spacing keys such as padding, verticalSeparation, horizontalSeparation, and arcRadius, plus marker controls like showMarkers and markerRadius.

For complete syntax details across all four notations, see the Mermaid railroad documentation.