File format

A document is a .jsonl (JSON Lines) file: one JSON object per line. Each line is a bullet, the removal of a bullet, or the metadata of the document.

{"type": "metadata", "favorites": ["01M48R76SB7697KM1N15N6QT4G"]}
{"id": "01M48R76SB7697KM1N15N6QT4G", "parent": "", "index": "a0", "type": "text", "text": "Hello"}
{"id": "01M48R76SJ8SGVJ4JA1EAE16ZQ", "parent": "01M48R76SB7697KM1N15N6QT4G", "index": "a0", "type": "checkbox", "text": "Buy milk", "checked": false}
{"id": "01M48R76SB7697KM1N15N6QT4G", "parent": "", "index": "a0", "type": "text", "text": "Hello world"}
{"id": "01M48R76SJ8SGVJ4JA1EAE16ZQ", "deleted": true}

Here “Hello” was changed to “Hello world”, and its child “Buy milk” was removed.

Append-only structure

Lines are only added at the end of the file. A line already written never changes.
The last line about an id is the one that counts. A change writes the whole bullet again.
A removed bullet gets a tombstone: {"id": "...", "deleted": true}.
A metadata line holds all of the metadata. The last one counts.
Now and then, TreeWrite rewrites the file with one line per bullet, the metadata first.
Lines TreeWrite cannot read are kept, also when it rewrites the file.

Bullet fields

The fields every bullet has. The fields of each type are in Bullet types. A field that is not required is omitted when it is empty.

Field	Type	Required	Description
`id`	`string`	Yes	Unique id, a ULID
`parent`	`string`	Yes	`id` of the parent. Empty at the root of the document
`index`	`string`	Yes	Position among the siblings, a fractional index. Siblings are sorted by it as plain strings
`type`	`string`	Yes	The type, which sets the other fields
`note`	`string`	No	The note
`tags`	`string[]`	No	`id` of each tag of the bullet
`start`	`string`	No	The date, as `YYYY-MM-DD`, or `YYYY-MM-DDTHH:MM` with a time
`end`	`string`	No	The end of the date, in the same form as `start`, and after it
`repeat`	`string`	No	How the date repeats
`card`	`object`	No	The flashcard of the bullet
`collapsed`	`boolean`	No	Whether the children are hidden. Omitted when `false`

Dates

start and end have no time zone. Both are days, or both have a time. The day of the end is included.

{"id": "...", "type": "text", "text": "Trip", "start": "2026-12-20", "end": "2027-01-05"}
{"id": "...", "type": "text", "text": "Team meeting", "start": "2026-10-19T14:00", "end": "2026-10-19T15:00", "repeat": "FREQ=WEEKLY;BYDAY=MO,WE"}

repeat is an RRULE of iCalendar that starts at start. Any other rule is kept as it came, and the bullet shows no repeat.

Part	Values
`FREQ`	`DAILY`, `WEEKLY`, `MONTHLY` or `YEARLY`
`INTERVAL`	From `1` to `9999`. Omitted for `1`
`BYDAY`	For `WEEKLY`, the weekdays, as `MO,WE,FR`. For `MONTHLY`, a weekday of the month, as `2WE` (the second Wednesday) or `-1FR` (the last Friday)
`WKST`	Only `MO`

Cards

The card of a flashcard is {} until its first review. Then it holds:

Field	Type	Description
`due`	`string`	Study day the card is due on, as `YYYY-MM-DD`
`last`	`string`	Study day of its last review, as `YYYY-MM-DD`
`stability`	`number`	FSRS stability, in days
`difficulty`	`number`	FSRS difficulty, from `1` to `10`
`reps`	`number`	How many times it was reviewed
`lapses`	`number`	How many times it was forgotten
`suspended`	`boolean`	Whether it is suspended. Omitted when `false`

due, last, stability, difficulty, reps and lapses are all there, or none of them. A study day starts at the hour of dayStartsAt.

Metadata

The settings of the document. Every field is optional, except type.

Field	Type	Description
`type`	`string`	Always `metadata`
`theme`	`object`	Colors of the document
`home`	`object`	Title, icon and background of the Home
`publish`	`object`	How the document is published
`features`	`object`	Sidebar features turned off
`tags`	`object[]`	The tags, in the order they are shown
`favorites`	`string[]`	`id` of each favorite bullet, in the order they are shown
`flashcards`	`object`	How flashcards are scheduled
`git`	`object`	Settings of the Git integration

theme

Field	Type	Description
`hue`	`number`	Hue of the neutral colors, from `0` to `360`. Default `0`
`saturation`	`number`	Saturation of the neutral colors, from `0` (gray) to `100`. Default `0`
`primary`	`string`	Main accent color, as a hex color. Default `#f21616`
`secondary`	`string`	Second accent color. Default `#ffa903`
`tertiary`	`string`	Third accent color. Default `#605cac`
`colorScheme`	`string`	`light` or `dark`. Default `dark`
`codeSyntax`	`string`	Colors of code blocks, such as `github`, `dracula` or `nord`. Default `github`

home

Field	Type	Description
`title`	`string`	Title of the Home. Default `Home`
`icon`	`string`	An emoji, a file name in the assets, or a URL
`background`	`string`	A color, a file name in the assets, or a URL
`position`	`number`	Vertical position of the background image, from `0` (top) to `100` (bottom). Default `50`

publish

Field	Type	Description
`url`	`string`	Address of the site, an `http` or `https` URL ending in `/`
`cmd`	`string`	Command that uploads the site. Never published

features

Field	Type	Description
`hidden`	`string[]`	Features turned off, any of `favorites`, `tags`, `calendar`, `flashcards` and `assets`

Field	Type	Description
`id`	`string`	Unique id, a ULID
`name`	`string`	Up to 40 characters, unique whatever the case
`color`	`string`	A hex color. Omitted for a tag in a dimmed color

flashcards

Field	Type	Description
`retention`	`number`	Desired retention, from `0.7` to `0.97`. Default `0.9`
`newPerDay`	`number`	New cards a day, from `0` to `9999`. Default `20`
`reviewsPerDay`	`number`	Reviews a day, from `0` to `9999`. Omitted for no limit
`dayStartsAt`	`number`	Hour a study day starts at, from `0` to `23`. Default `4`

git

Field	Type	Description
`enabled`	`boolean`	Whether the sync is on. Default `false`
`mode`	`string`	`sync` or `backup`. Default `sync`
`idleMinutes`	`number`	Minutes after the last change before a sync, from `0.5` to `1440`. Default `1`
`pullIntervalMinutes`	`number`	Minutes between pulls, or pushes in `backup` mode, from `0.5` to `1440`. Default `5`
`pullOnOpen`	`boolean`	Whether to pull when the document is opened, or push in `backup` mode. Default `true`
`commitMessage`	`string`	Commit message, where `{{file}}`, `{{date}}` and `{{hostname}}` are replaced. Default `{{file}} from {{hostname}} at {{date}}`

Review log

Each grade given to a flashcard is a line of ./treewrite/{filename.jsonl}/reviews.jsonl. It is append-only too: undoing a grade adds a line with undone.

{"card": "01M48R76RF8JE7GJW22BHY6FC1", "at": "2026-10-16T21:34:05", "rating": 3}
{"card": "01M48R76RF8JE7GJW22BHY6FC1", "at": "2026-10-16T21:34:05", "undone": true}

Field	Type	Description
`card`	`string`	`id` of the bullet graded
`at`	`string`	When, as `YYYY-MM-DDTHH:MM:SS`, on the local clock
`rating`	`number`	`1` Again, `2` Hard, `3` Good or `4` Easy. Not on an `undone` line
`undone`	`boolean`	`true` to cancel the grade of the same `card` at the same `at`