File Format

How Braidr stores your data as plain files you can read, edit, and version.

Philosophy

Braidr stores everything as plain text files in a folder on your computer. There is no database, no proprietary format, and no cloud dependency. You can open these files in any text editor, track them with git, sync them with Dropbox, and read them decades from now.

Project structure

my-novel/
├── Frodo.md              # Character POV file
├── Aragorn.md            # Character POV file
├── Gandalf.md            # Character POV file
├── timeline.json         # Reading order & all metadata
└── notes/
    ├── notes-index.json  # Notes index and folder structure
    ├── middle-earth.html # Knowledge base note
    └── magic-system.html # Knowledge base note

Character files (.md)

Each POV character has one markdown file. The file format is designed to be both machine-readable and human-readable:

---
character: Frodo
---

## The Shire (3)
Frodo inherits the Ring and must leave the safety of home.

1. Bilbo's birthday party — Bilbo vanishes. Frodo inherits
   #bag_end and the #ring. #gandalf warns him. #bilbo
2. Gandalf reveals the Ring's true nature — Seventeen years
   pass. #gandalf returns and tells Frodo what the #ring
   really is.
3. Leaving the Shire with Sam — Frodo and #sam set out from
   #bag_end under cover of darkness.

## The Journey (4)
The hobbits make their way east toward Rivendell.

4. ==**Meeting Strider at the Prancing Pony**== The hobbits
   arrive in #bree. #aragorn reveals himself. #prancing_pony
5. A Knife in the Dark — The Nazgûl attack on #weathertop.
   Frodo is stabbed.
   - This is the first time Frodo puts on the Ring voluntarily
   - Establishes the Nazgûl as a real physical threat
6. Flight to the Ford — Arwen rescues Frodo and carries him
   to #rivendell. #arwen
7. The Council of Elrond — The Fellowship is formed at
   #rivendell. #gandalf #aragorn #elrond

Format details

• YAML frontmatter — the --- block at the top contains character: Name.
• Section headers — ## Section Name (count) defines plot point sections. The count in parentheses is the number of scenes in that section.
• Section descriptions — prose text after a header and before the first numbered scene.
• Numbered scenes — 1. Scene title — description. Numbers are sequential within the character file.
• Highlighted scenes — ==**Bold title**== marks key scenes with visual emphasis.
• Tags — inline #tag_name anywhere in a scene. Underscores are converted to spaces in the UI.
• Sub-notes — indented bullet points under a scene for additional notes or details.

Timeline file (timeline.json)

The timeline.json file stores everything that isn't in the character markdown files:

• Scene positions — the reading order of every scene across all characters. Each scene is identified by character name + scene number.
• Chapter markers — positions and names of chapter breaks.
• Scene connections — links between related scenes across POVs.
• Draft content — the full text of each scene's drafts (V1, V2, etc.) with timestamps and version notes.
• Scene metadata — status, synopsis, custom field values, and scratchpad notes.
• Tag definitions — the master list of tags with their categories.
• Custom field definitions — names, types, and options for custom metadata fields.
• Character settings — display colors, order in the UI.

Notes directory

The notes/ folder contains:

• HTML files — one per note, named by slug (e.g., middle-earth.html). HTML is used because notes support rich text formatting.
• notes-index.json — an index file that maps note slugs to titles, folder assignments, and creation/modification timestamps.

Git compatibility

Braidr's file format is designed to work well with git:

• Character files produce clean, readable diffs when you add, edit, or reorder scenes.
• timeline.json is formatted with consistent indentation so structural changes produce meaningful diffs (though large rearrangements may generate noisy diffs).
• Notes are individual files, so adding or editing one note doesn't affect others in the diff.

Editing outside Braidr

You can edit character .md files in any text editor and Braidr will pick up the changes when you open the project (or when the file changes if the project is already open). This is useful for:

• Quick edits in your favorite text editor.
• Bulk operations with find-and-replace.
• Writing in Obsidian or another markdown editor.
• Programmatic editing with scripts.

Just keep the format consistent: YAML frontmatter, ## section headers with counts, and numbered scenes with #tags.