# Railroad diagrams in docs-site

The docs frontend now supports fenced `railroad` blocks for grammar-style syntax diagrams.

Use this when a Mermaid flowchart would be too broad and you want to explain a concrete production rule, token pattern, or mini-language shape.

## How the block works

- the fence language is `railroad`
- the block body is JSON
- the JSON maps directly to the supported `railroad-diagrams` node types
- a top-level array is treated as `Diagram(items)` automatically
- bare strings inside `items` become `Terminal(...)`

## Supported node types

| Type             | Required fields | Notes                                                   |
| ---------------- | --------------- | ------------------------------------------------------- |
| `Terminal`       | `text`          | Literal token or fixed keyword                          |
| `NonTerminal`    | `text`          | Production or placeholder label                         |
| `Comment`        | `text`          | Annotation text                                         |
| `Skip`           | none            | Empty branch / spacer                                   |
| `Sequence`       | `items`         | Concatenation                                           |
| `Choice`         | `items`         | Optional `normal` chooses the straight path             |
| `Optional`       | `item`          | Optional `skip: "skip"` keeps omission on the main line |
| `OneOrMore`      | `item`          | Optional `repeat` item between repetitions              |
| `ZeroOrMore`     | `item`          | Optional `repeat` and `skip` just like the library      |
| `Diagram`        | `items`         | Explicit root                                           |
| `ComplexDiagram` | `items`         | Explicit complex root                                   |

## Source example

```json
[
  { "type": "NonTerminal", "text": "identifier" },
  {
    "type": "ZeroOrMore",
    "item": {
      "type": "Sequence",
      "items": [".", { "type": "NonTerminal", "text": "identifier" }]
    }
  }
]
```

## Rendered example

```railroad
[
  { "type": "NonTerminal", "text": "identifier" },
  {
    "type": "ZeroOrMore",
    "item": {
      "type": "Sequence",
      "items": [
        ".",
        { "type": "NonTerminal", "text": "identifier" }
      ]
    }
  }
]
```

## Choice example

```railroad
{
  "type": "Diagram",
  "items": [
    {
      "type": "Choice",
      "normal": 1,
      "items": [
        "draft",
        "published",
        "archived"
      ]
    },
    { "type": "NonTerminal", "text": "record" }
  ]
}
```

## Authoring tips

- start with a top-level array for the common linear case
- use strings for literals and `NonTerminal` for named grammar pieces
- wrap repeated fragments in `Sequence` before putting them in `ZeroOrMore` or `OneOrMore`
- keep labels short; the library uses simple text metrics and gets grumpy when asked to measure a novel