Create SVG Syntax Diagrams with JavaScript and d3.js – Railroad Diagram

Railroad Diagram is a vanilla JavaScript library that creates clean, professional syntax diagrams for documenting programming language grammars and formal syntax rules.

It uses the d3.js library to transform declarative syntax definitions into visual railroad diagrams that help you understand complex parsing rules and language structures.

Features:

• SVG rendering: Generates clean vector graphics with proper stroke handling and consistent visual styling.
• Grid-based alignment: Uses a 24-pixel grid system that ensures precise positioning and professional appearance.
• Global API access: Provides all functionality through window.RailroadDiagrams for straightforward integration.
• Interactive navigation: Enables click-to-jump functionality between related syntax rules within the same document.
• TypeScript definitions: Includes complete type definitions for development environments that support static typing.
• Debug visualization: Offers an optional debugging mode that displays layout boundaries and grid alignment guides.

Use Cases:

• Language documentation projects: Creating comprehensive grammar references for programming languages, domain-specific languages, or configuration file formats where visual flow diagrams help users understand parsing precedence and alternative paths.
• Parser development workflows: Documenting complex parsing rules during compiler or interpreter development, particularly when working with recursive descent parsers or when explaining grammar ambiguities to team members.
• API specification documentation: Visualizing request format patterns, URL structure rules, or query parameter syntax where traditional text documentation becomes unwieldy for users to follow.
• Educational content creation: Building interactive syntax guides for programming tutorials, language learning resources, or computer science coursework where visual representation aids comprehension of formal grammar concepts.

How to use it:

1. Add the necessary d3.js to your HTML file, followed by the Railroad Diagram Library’s JavaScript and CSS files.

<link rel="stylesheet" href="/path/to/diagram.css">
<script src="/path/to/cdn/d3.js"></script>
<script src="/path/to/diagram.js"></script>

2. Define diagrams inside a <script> tag with type="text/railroad". The data-rule attribute gives your diagram a name, which is useful for linking between diagrams.

<script type="text/railroad" data-rule="your-name">
  ...
</script>

3. Use the following functions to build the structure.

• textBox(text, className): The basic building block. Use it for terminals (literal strings) and non-terminals (references to other rules).
• sequence(...elements): Arranges elements one after another, horizontally.
• stack(...elements): Creates a vertical stack of choices, like an “OR” condition.
• loop(...elements): Creates a repeating loop around a set of elements.
• bypass(...elements): Makes a set of elements optional by creating a path that skips over them.

<script type="text/railroad" data-rule="expression">
  sequence(
    textBox("term", "nonterminal"),
    bypass(sequence(
      textBox("\"+\"", "terminal"),
      textBox("expression", "nonterminal")
    ))
  )
</script>

<script type="text/railroad" data-rule="factor">
  stack(
    textBox("constant", "nonterminal"),
    textBox("variable", "nonterminal"),
    sequence(
      textBox("(", "terminal"),
      textBox("expression", "nonterminal"),
      textBox(")", "terminal")
    )
  )
</script>

<script type="text/railroad" data-rule="constant">
  loop(textBox("digit", "nonterminal"))
</script>

4. Find all the diagram definitions and render them.

• gridSize: Sets the pixel size of the underlying grid system
• debugMode: Enables visual debugging overlays that show element boundaries and alignment guides

document.addEventListener('DOMContentLoaded', function() {
  window.RailroadDiagrams.renderDiagramScripts({
    gridSize: 24,
    debugMode:false
  });
});

5. While defining diagrams directly in HTML script tags is great for static documentation, you can also create them programmatically. This is useful for dynamic applications where the diagrams might change based on user input or other data.

// Access expression builders and the Diagram class
const { textBox, sequence, stack } = window.RailroadDiagrams.Expression;
const { Diagram } = window.RailroadDiagrams;

// 1. Define a container element in your HTML
// 2. Get a reference to the container
const diagramContainer = document.getElementById("diagram-container");
// 3. Create a new Diagram instance
// Pass the container element, grid size (e.g., 24px), and debug flag
const diagram = new Diagram(diagramContainer, 24, true);
// 4. Build a complex expression using the API functions
const myExpression = sequence(
    textBox("START", "terminal"),
    stack(
        textBox("option1", "nonterminal"),
        textBox("option2", "nonterminal"),
        textBox("option3", "nonterminal")
    ),
    textBox("END", "terminal")
);
// 5. Add the expression to the diagram as a named rule
diagram.addRule("My Programmatic Rule", myExpression);

FAQs:

Q: How do I customize the styling of the diagrams?
A: The appearance is controlled by the diagram.css file. You can override the CSS rules in your own stylesheet. The key classes to target are .terminal for literal text and .nonterminal for rule references.

Q: What happens if my syntax definitions contain errors or malformed expressions?
A: The library will fail silently for malformed expressions, rendering nothing in that diagram slot. Enable debug mode during development to get visual feedback about element boundaries and potential layout issues that might indicate syntax problems.

Q: Can I generate diagrams programmatically instead of using script tags?
A: Yes, you can access the core API directly through window.RailroadDiagrams and create Diagram instances manually. This approach gives you more control over rendering timing and allows for dynamic diagram generation based on user input or external data sources.

Q: How do I optimize performance when displaying many syntax diagrams on a single page?
A: The library renders all diagrams during the initial renderDiagramScripts call, which can impact page load performance with many complex diagrams. Consider lazy loading diagrams as they enter the viewport, or splitting large grammar documentation across multiple pages to maintain responsive user experience.

Changelog:

09/20/2025

• Automatic diagram rendering and click handler setup on DOM ready
• Regex-based tokenizer with named capture groups (.NET style)
• Node.js compatibility while preserving browser functionality
• Professional test framework with clear pass/fail expectations
• Removed manual renderDiagramScripts() calls from HTML files
• Enhanced validation handles strings with function-like patterns correctly
• Consistent API design – both features auto-initialize
• Better error reporting and test output clarity
• Robust tokenization prevents false positives on string content
• Function name whitelisting via proper parsing
• Dangerous pattern detection only outside string literals

v0.2.0 (09/20/2025)

• Fixed validation errors by removing overly restrictive character validation
• Refactored _invalidate method into focused functions (_renderRule, _renderRuleTerminals, _renderRuleExpression)
• Made baseline nomenclature consistent throughout codebase
• Fixed click navigation with proper syntax-rule IDs in odata.html

v0.0.3 (09/18/2025)

• Replace config override complexity with CSS-driven sizing
• CSS custom properties are now single source of truth for all sizing
• Split debugMode into separate showGrid and showBounds flags
• Remove all references to old config override system
• Clean API: renderDiagramScripts() with optional debug flags