mermaid/docs/syntax/railroad.md

Warning

THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

Please edit the corresponding file in /packages/mermaid/src/docs/syntax/railroad.md.

Railroad Diagrams (v<MERMAID_RELEASE_VERSION>+)

Railroad diagrams (also known as syntax diagrams or grammar diagrams) are a visual representation of context-free grammars using EBNF (Extended Backus-Naur Form) notation. They provide a graphical way to understand and document language syntax, making complex grammar rules easier to comprehend.

Railroad diagrams were first popularized by Niklaus Wirth in his "Pascal User Manual" (1974) and remain widely used today, notably on JSON.org for documenting the JSON syntax.

Mermaid can render Railroad diagram visualizations from EBNF notation.

railroad-diagram
title "Digit Definition"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

railroad-diagram
title "Digit Definition"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Syntax

Railroad diagrams use EBNF (Extended Backus-Naur Form) notation to define grammar rules. Mermaid supports both W3C and ISO 14977 EBNF notation styles.

Basic Structure

• Start with railroad-diagram keyword to begin the diagram
• Optionally add a title followed by a quoted string
• Define grammar rules using the format: rule_name = definition ;
• Each rule must end with a semicolon (;)

EBNF Notation

Terminals and Non-terminals

Terminals are literal strings enclosed in quotes:

• "text" - double quotes
• 'text' - single quotes

Non-terminals are identifiers that reference other rules:

• identifier - references another rule

railroad-diagram
letter = "a" | "b" | "c" ;
identifier = letter ;

railroad-diagram
letter = "a" | "b" | "c" ;
identifier = letter ;

Sequence (Concatenation)

Elements appearing one after another define a sequence:

• W3C notation: A B C
• ISO 14977 notation: A , B , C

railroad-diagram
greeting = "Hello" " " "World" ;

railroad-diagram
greeting = "Hello" " " "World" ;

Choice (Alternation)

The pipe symbol (|) indicates alternatives:

railroad-diagram
sign = "+" | "-" ;

railroad-diagram
sign = "+" | "-" ;

Optional Elements

Optional elements can appear zero or one time:

• W3C notation: A?
• ISO 14977 notation: [ A ]

railroad-diagram
title "Optional Sign"

sign = "+" | "-" ;
number = sign? digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

railroad-diagram
title "Optional Sign"

sign = "+" | "-" ;
number = sign? digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Repetition

Zero or more repetitions:

• W3C notation: A*
• ISO 14977 notation: { A }

One or more repetitions:

• W3C notation: A+

railroad-diagram
title "Identifier with Repetition"

identifier = letter ( letter | digit | "_" )* ;
letter = "a" | "b" | "c" | "d" | "e" ;
digit = "0" | "1" | "2" ;

railroad-diagram
title "Identifier with Repetition"

identifier = letter ( letter | digit | "_" )* ;
letter = "a" | "b" | "c" | "d" | "e" ;
digit = "0" | "1" | "2" ;

Grouping

Parentheses group elements together:

• ( A B )

railroad-diagram
expression = term ( ( "+" | "-" ) term )* ;
term = "number" ;

railroad-diagram
expression = term ( ( "+" | "-" ) term )* ;
term = "number" ;

Comments

Comments can be added using either style:

• W3C notation: /* comment */
• ISO 14977 notation: (* comment *)

Comments are ignored during parsing and do not appear in the rendered diagram.

Special Sequences

Special sequences (ISO 14977 only) describe elements that cannot be easily expressed in EBNF:

• ? description ?

Exception

The minus operator excludes certain alternatives:

• A - B (match A but not B)

Examples

Simple Number Grammar

railroad-diagram
title "Number Grammar"

sign = "+" | "-" ;
number = sign? digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

railroad-diagram
title "Number Grammar"

sign = "+" | "-" ;
number = sign? digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Expression Grammar

railroad-diagram
title "Arithmetic Expression Grammar"

expression = term ( ( "+" | "-" ) term )* ;
term = factor ( ( "*" | "/" ) factor )* ;
factor = number | "(" expression ")" ;
number = digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

railroad-diagram
title "Arithmetic Expression Grammar"

expression = term ( ( "+" | "-" ) term )* ;
term = factor ( ( "*" | "/" ) factor )* ;
factor = number | "(" expression ")" ;
number = digit+ ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

JSON Grammar (Simplified)

railroad-diagram
title "JSON Grammar"

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

railroad-diagram
title "JSON Grammar"

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

URL Grammar

railroad-diagram
title "URL Grammar"

url = protocol "://" domain path? ;
protocol = "http" | "https" | "ftp" ;
domain = label ( "." label )* ;
label = letter ( letter | digit | "-" )* ;
path = "/" segment ( "/" segment )* ;
letter = "a" | "b" | "c" ;
digit = "0" | "1" | "2" ;
segment = letter+ ;

railroad-diagram
title "URL Grammar"

url = protocol "://" domain path? ;
protocol = "http" | "https" | "ftp" ;
domain = label ( "." label )* ;
label = letter ( letter | digit | "-" )* ;
path = "/" segment ( "/" segment )* ;
letter = "a" | "b" | "c" ;
digit = "0" | "1" | "2" ;
segment = letter+ ;

Visual Elements

Railroad diagrams use distinct visual elements to represent different grammar constructs:

• Terminals: Rounded rectangles that inherit the active Mermaid theme
• Non-terminals: Regular rectangles that inherit the active Mermaid theme
• Lines and Arrows: Theme-aware paths connecting elements
• Start/End Markers: Small circles at the beginning and end of rules
• Branches: Curved paths for choices
• Loops: Backward paths for repetition

Theme Integration

Railroad diagrams inherit colors and typography from the active Mermaid theme by default. You can still override individual railroad styles through the railroad config block when you need diagram-specific adjustments.

Limitations

• The hand-drawn look (look: handDrawn) is not currently supported for railroad diagrams.

Notation Reference

Feature	W3C Notation	ISO 14977 Notation	Description
Terminal	"text" or 'text'	"text" or 'text'	Literal string
Non-terminal	identifier	identifier	Rule reference
Sequence	A B	A , B	Concatenation
Choice	A | B	A | B	Alternative
Optional	A?	[ A ]	Zero or one
Repetition (0+)	A*	{ A }	Zero or more
Repetition (1+)	A+	-	One or more
Grouping	( A B )	( A B )	Group elements
Comment	/* text */	(* text *)	Comment
Special	-	? text ?	Special sequence
Exception	A - B	A - B	Exclusion

Best Practices

1. Keep rules simple: Break complex rules into smaller, reusable components
2. Use meaningful names: Choose descriptive names for non-terminals
3. Add titles: Use the title keyword to provide context for the grammar
4. Group related rules: Define related grammar rules together
5. Use consistent notation: Stick to either W3C or ISO 14977 notation style throughout your diagram

References

• ISO/IEC 14977:1996 - EBNF Standard
• W3C EBNF Notation
• Wikipedia: Extended Backus-Naur Form
• Wikipedia: Syntax Diagram