# nemoboard

> nemoboard (https://nemoboard.com) is an infinite-canvas diagramming tool where any card can open into a board of its own, called a sub-board. Every board is a plain markdown file ending in `.nemo.md`. This guide is for language models: it explains how to write those files from a description, a spec or a list, so a person can paste them into nemoboard.

nemoboard runs in the browser and has no API. You write each board's file and hand the boards to the person, as a .zip if you can create files (see "Getting the boards into nemoboard" at the end). The docs for people are at https://nemoboard.com/docs/, and the file format has its own page there: https://nemoboard.com/docs/file-format.html.

## A complete board

This is a whole board file. Copy its structure.

```markdown
---
nemoboard: 1
---

# Order fulfilment

How an order goes from checkout to the customer's door.

## Cards

### Order placed {#placed}
@ shape=terminator at=0,10 size=180x64 color=green

### Check stock {#stock}
@ shape=process at=260,0 size=200x84

Look up each item in the warehouse system.

### In stock? {#in-stock}
@ shape=decision at=540,-33 size=150x150 color=amber

### Pick and pack {#pack}
@ shape=process at=770,0 size=200x84 color=blue sub=./pick-and-pack.nemo.md

Picking, packing and the shipping label.

### Back-order {#backorder}
@ shape=process at=515,200 size=200x84 color=red

### Shipped {#shipped}
@ shape=terminator at=1050,10 size=180x64 color=green

### Notes {#notes}
@ shape=note at=0,200 size=300x170

#### Open questions

- Who tells the customer about a back-order?
- [ ] Agree a target time for packing

## Connections

- placed -> stock
- stock -> in-stock
- in-stock -> pack : yes
- in-stock -> backorder : no
- backorder --> stock : restocked {route=curved}
- pack -> shipped
```

## The file

- It starts with frontmatter: `nemoboard: 1` between two `---` lines.
- The frontmatter can also set the board's typeface: `font: serif`, `font: mono` or `font: rounded` (without it, sans). Leave it out unless the person asks.
- `# Title` is the board's title. Text after it, up to the first `##`, describes the board.
- `## Cards` holds the cards, and `## Connections` the connections between them. Write them in that order.

## Cards

- `### Title {#id}` starts a card. The id is how connections name the card: letters, digits, `-`, `_` and `.`, unique on the board. Use short lowercase ids with dashes (`check-stock`). Always write the id.
- The line straight after the heading is the card's attributes: `@ key=value key=value`. Values with spaces go in double quotes: `who="Budget owner"`.
- Everything after that, up to the next `###`, is the card's text, in markdown: paragraphs, lists, `- [ ]` tasks, **bold**, links, tables and code blocks.
- Headings in a card's text are written three levels deeper than they show: `####` for a top heading, then `#####` and `######`. Never start a line in a card's text with `## ` or `### `, outside a code block: that would end the card.
- A title is one line; write `<br>` for a line break in it. Keep titles short (two to five words): the card's text is for detail, and a `note` card is better for anything long.

## Card attributes

- `shape=`: one of the shapes below. Without it, a card is a `process`.
- `at=x,y`: where the card's top-left corner sits, in pixels. x grows to the right and y downwards; negative numbers are fine.
- `size=WxH`: the card's width and height in pixels. Without it, the shape's usual size (below).
- `color=`: one of `slate`, `blue`, `teal`, `green`, `amber`, `red`, `violet`, `pink`. Without it, the card has no colour.
- `sub=./name.nemo.md`: the card's sub-board, as a path relative to this file (see "Sub-boards").
- `locked`: the card can't be moved.
- `step`: on `process` cards, shows a process step's three extra parts: Time above the card, Where and Who below it. The card's title is the What. Give their text with `time="…"`, `where="…"` and `who="…"`, and make the card 102 pixels taller than usual (`size=200x186`) to make room for them.
- `ref=`: on `port` cards only (see "Sub-boards").
- `src=`: on `image` cards only, a picture file in the project's `images/` folder. You can't make pictures, so don't write image cards.

## Shapes

| Shape | Usual size | For |
| --- | --- | --- |
| `process` (Process) | 200x84 | A step, task or thing: the usual card. |
| `decision` (Decision) | 150x150 | A diamond: a question with two or more outcomes, labelled on its connections. |
| `terminator` (Start / End) | 180x64 | A rounded pill: where a flow starts or ends. |
| `data` (Data) | 200x84 | A slanted box: data going in or out. |
| `document` (Document) | 200x96 | A page with a wavy foot: a document or report. |
| `database` (Database) | 160x110 | A cylinder: a database or other store. |
| `burst` (Kaizen burst) | 170x110 | A red cloud (a kaizen burst): a problem, or something to improve, next to the step it is about. |
| `note` (Note) | 260x200 | A sticky note for longer markdown text. |
| `frame` (Frame) | 480x320 | A labelled box drawn behind other cards, to group them. |
| `text` (Text) | 220x40 | Text with no box: a heading or a label on the board. |
| `port` (Port) | 140x40 | Inside a sub-board, stands for a card outside it (see "Sub-boards"). |
| `image` (Image) | 240x180 | A picture from the project. Not for models to write. |

## Connections

One per line under `## Connections`: `- from -> to : label {route=curved}`. `from` and `to` are card ids on the same board. The label (after ` : `) and the `{…}` are optional.

| Written | Drawn as |
| --- | --- |
| `->` | Solid, with an arrow at the end |
| `<->` | Solid, with arrows at both ends |
| `-->` | Dashed, with an arrow at the end |
| `---` | Solid, with no arrows |
| `-.-` | Dashed, with no arrows |
| `<-->` | Dashed, with arrows at both ends |

Two cards can have several connections, in either direction (a request and its response), and a card can connect to itself (`- retry -> retry : again`), for a step that repeats.

`{route=…}` is `orthogonal` (right angles, the usual), `curved` or `straight`. Curved suits a connection that loops back.

`{start=… end=…}` chooses the side of each card the connection meets: `top`, `right`, `bottom` or `left` (`{start=top end=top}`, or just `{end=left}`). Leave them out unless the person asks for a side: without them, each end meets the side facing the other card. Several options go in one `{…}`: `{route=curved start=bottom}`.

## Laying a board out

- Place every card with `at=`. Cards without it are put on a plain grid below the others, which the person then has to arrange.
- A flow reads left to right. Put cards about 280 pixels apart (a 200-pixel card and an 80-pixel gap), with more room where a connection has a label.
- Line a row up by the cards' centres: `y = middle of the row − height ÷ 2`. In the example, the row's middle is y=42: the 84-pixel process cards are at y=0, the 64-pixel terminators at y=10 and the 150-pixel decision at y=−33.
- Put a decision's other outcome below it, about 200 pixels down, and exceptions, notes and problems below the main row.
- Group related cards with a `frame` behind them, 40 pixels bigger than the group on every side, and use `text` cards for headings.
- Keep a board to about 5–15 cards. When a step has detail of its own, give its card a sub-board rather than adding more cards around it: that's what nemoboard is for.
- Use colour sparingly and the same way throughout: green for starts and good outcomes, red for problems, amber for decisions, for example.

## Sub-boards

A project is a folder. The top board is `index.nemo.md`. A card opens into its sub-board with `sub=`, a path relative to the file the card is in. Sub-boards of the top board sit beside it; sub-boards of any other board sit in a folder named after that board:

```text
index.nemo.md                 the top board
pick-and-pack.nemo.md         the sub-board of a card on index.nemo.md
pick-and-pack/label.nemo.md   the sub-board of a card on pick-and-pack.nemo.md
```

So on `index.nemo.md` a card has `sub=./pick-and-pack.nemo.md`, and on `pick-and-pack.nemo.md` a card has `sub=./pick-and-pack/label.nemo.md`.

Connections only join cards on the same board. Inside a sub-board, a `port` card can stand for a card outside it: `ref=` is that outside card's id, and its title is that card's title. Put ports that lead in on the left and ports that lead out on the right. Here is the sub-board of "Pick and pack" from the example above:

```markdown
---
nemoboard: 1
---

# Pick and pack

## Cards

### In stock? {#in-in-stock}
@ shape=port at=-220,22 size=140x40 ref=in-stock

### Pick items {#pick}
@ shape=process at=0,0 size=200x84

### Pack box {#box}
@ shape=process at=280,0 size=200x84

### Print label {#label}
@ shape=process at=560,0 size=200x84 sub=./pick-and-pack/label.nemo.md

### Shipped {#out-shipped}
@ shape=port at=840,22 size=140x40 ref=shipped

## Connections

- in-in-stock -> pick
- pick -> box
- box -> label
- label -> out-shipped
```

A `sub=` path whose file you don't write is fine: nemoboard opens it as an empty board when the card is opened.

## Before you answer, check

1. Each file starts with the frontmatter `nemoboard: 1`, then `# Title`, `## Cards` and `## Connections`.
2. Each card is `### Title {#id}` with an id unique on its board, and its `@` line comes straight after the heading.
3. Every connection's two ends are ids of cards on that same board.
4. Shapes and colours come only from the lists above, and values with spaces are in double quotes.
5. Headings in card text start with `####` or more.
6. Every card has `at=`, and the cards don't overlap.
7. Each file is at its path in the .zip (`Order fulfilment/index.nemo.md`, `Order fulfilment/pick-and-pack.nemo.md`…), or, if you can't make one, in its own code block headed with its path.

## Getting the boards into nemoboard

Give the person the boards the easiest way you can, and tell them how to open them in a sentence or two.

**As a .zip, if you can create files** (for example by running code). This is the better way, for one board as well as many:

1. Put the files in one folder named after the project, laid out as in "Sub-boards" (`Order fulfilment/index.nemo.md`, `Order fulfilment/pick-and-pack.nemo.md`…).
2. Zip the folder and give the person the .zip to download.
3. Tell them: on https://nemoboard.com, choose *Import ▸ .zip file…* in the project menu and pick the .zip. It opens as a new project named after the folder, with every sub-board in place, on phones too.

**Otherwise, as text to paste.** Put each file in its own code block, headed with its path, and tell the person:

- **One board:** on https://nemoboard.com, choose *New in-browser project…* in the project menu, press ⌘/ (Ctrl+/ on Windows and Linux) to open the board's markdown, select all of it and paste the file over it. The board redraws straight away.
- **Its sub-boards:** double-click the card to go inside, open the markdown the same way, and paste that board's file.
- **Many boards:** pasting each one gets slow, so they can save the files in a folder, as laid out above, zip it and choose *Import ▸ .zip file…*. In Chrome or Edge, *Open folder…* opens the folder directly.