Import and Export (Markdown)

Boards can be exported to a single Markdown file and later re-imported to reconstruct the board.

Design goals

Human-readable and diff-friendly
Git-friendly (review changes in PRs)
Round-trip safe: export → import → identical board

Canonical structure

Board frontmatter

A YAML frontmatter block defines board metadata:

Field	Required	Description
`board`	✓	Board name
`id`	✓	Board UUID
`created`	optional	ISO 8601 timestamp
`updated`	optional	ISO 8601 timestamp
`width`	optional	Canvas width in pixels
`height`	optional	Canvas height in pixels

Note blocks

Each note appears as a repeated section:

## Note: <uuid> heading
Metadata lines (title:, x:, y:, color:, optional type:, description:, relationships:, timestamps)
A --- delimiter line
Markdown content body

Canonical example

---
board: "Board Name"
id: "abc123"
created: 2026-02-28T10:00:00Z
updated: 2026-02-28T15:30:00Z
width: 6000
height: 30000
---
 
## Note: 11111111-1111-1111-1111-111111111111
title: Epic — Reduce checkout friction
x: 120
y: 140
color: orange
type: Epic
description: Short summary of this epic.
relationships: [{"noteId":"222...","title":"Related note"}]
created: 2026-02-28T10:05:00Z
updated: 2026-02-28T10:06:00Z
---
**Goal:** reduce steps to purchase.
 
- Remove redundant address confirmation
- Add express payment options

Import behaviour

Preview: the import UI validates the file and shows board name, note count, and a sample of note titles.
Partial import: if some notes fail parsing, you can import the valid subset with a warning.
Merge: imported content merges into the current board (same board ID is preserved).

Common pitfalls

Symptom	Likely cause
Notes missing after import	Missing `---` delimiter before content body
Note has wrong colour	Invalid `color:` value (must be `yellow`, `blue`, `green`, `pink`, `orange`, or `purple`)
Note in wrong position	Non-numeric `x:` or `y:` values
Import fails entirely	Corrupted YAML frontmatter

Round-trip guarantee

The serialiser and parser are designed to round-trip: exporting and re-importing the same board produces an identical board state. If you edit the .md file manually, ensure you follow the canonical format above.