# roadflow markup notation

Text format for the **Markup** panel at [roadflow.io](https://roadflow.io). Paste or edit this text — the canvas stays in sync.

## Quick start

```text
Road
Product launch|Ship MVP to early users
#6366f1
@ MVP spec|https://example.com/spec.pdf
Lane
Backend
Auth API|OAuth + sessions|08/07/2026|done
Core routes|REST handlers|22/07/2026|in_progress
@ API design|https://example.com/api.md
Lane
Frontend
UI shell|App frame + nav|05/08/2026|pending
Road
Go-to-market|First 10 customers
#ec4899
Lane
Main
Landing page|Copy + CTA|15/08/2026|pending
-> Product launch / Core routes : Needs API ready
```

## Line types

| Line | Meaning |
|------|---------|
| `Road` | Start a road (major initiative). Next line: `{road name}\|{goal}`. |
| `#6366f1` | Optional road color (hex or CSS color). |
| `@ label\|url` | Artifact link. After a **road** header → goal artifacts; after a **step** → step artifacts. |
| `Lane` | Start a lane (parallel track). Next line: lane name. |
| `{step title}\|{notes}\|status` | Step (when date grid is **off**). |
| `{step title}\|{notes}\|date\|status` | Step (when date grid is **on**). |
| `{step title}\|{notes}\|date\|status\|milestone` | Milestone step (diamond). |
| `-> Road` | Connection from the step above to another road's **goal**. |
| `-> Road / Step` | Connection to a step on another lane (same or different road). |
| `-> Road / Step : note` | Connection with optional note (`:` separator; spaces optional). |

## Field rules

- **Separators:** `|` between fields on a step line; `/` between road and step in connections; `:` before a connection note.
- **Statuses:** `pending`, `in_progress`, `done` (exact spelling).
- **Dates:** `DD/MM/YYYY` when the date grid is enabled (e.g. `08/07/2026`).
- **Pipes in text:** Avoid `|` inside titles and notes — it breaks parsing.
- **Blank lines:** Ignored by the parser; safe while editing.
- **Keywords:** `Road` and `Lane` are case-sensitive section headers.
- **Artifacts:** use `@ label|url` under a road (goal links) or under a step (step links).

## Connections

- `-> Other road` — links to that road's goal card.
- `-> Other road / Step title` — links to a specific step (slash between road and step; spaces optional).
- Cannot connect to **this road's goal** or to **another step on the same lane**.
- Connecting to a step on **another lane of the same road** is allowed.

## Date grid

When **Date grid** is on in Preferences:

- Use the 4-field step line: `{step title}|{notes}|DD/MM/YYYY|status`.
- Steps snap to the calendar on the canvas.
- Turning the grid on re-parses markup with dates enabled.

When the date grid is off, omit the date field: `{step title}|{notes}|status`.

## Multiple roads

Each new `Road` block starts another initiative. Roads render as separate rows on the canvas.

## Export / import workflow

1. Draft markup in any editor (or generate from a spec).
2. Paste into the **Markup** panel in roadflow.
3. Fix any parse errors shown under the editor.
4. **Export → Text** downloads the same format.

## Machine-readable schema

```text
Road
{road name}|{goal}
#6366f1
@ {label}|{url}
Lane
{lane name}
{step title}|{notes}|pending
{step title}|{notes}|in_progress
{step title}|{notes}|done
{step title}|{notes}|done|milestone
{step title}|{notes}|01/07/2026|pending
-> {road name}
-> {road name} / {step title}
-> {road name} / {step title} : {note}
@ {label}|{url}
```

Curly braces `{…}` mark placeholders — do not include them in real markup.

## Agents / MCP

AI agents can create and edit roadflows over remote MCP at [mcp.html](https://roadflow.io/mcp.html) (protocol: `https://roadflow.io/mcp`). Prefer JSON tools when available; use this markup format with `roadflow_apply_markup` or when pasting into the Markup panel.

## See also

- [MCP for AI agents](https://roadflow.io/mcp.html) — Cursor config, tools, workspace modes
- [llms.txt](https://roadflow.io/llms.txt) — short overview for AI agents and crawlers
- In-app: **Notation** button in the markup panel (or **? → Instructions → §6 Markup**)
- Demo: **Fill with demo data** on an empty canvas loads a full example

Questions: [admin@roadflow.io](mailto:admin@roadflow.io)