The .book Format

Most writing apps treat a manuscript as a single long document, a flat list of arbitrary text snippets, or a folder of Markdown files. Incipor uses a different model: the .book package, a structured manuscript bundle that knows about scenes, chapters, and parts as first-class objects from the moment you start writing.

This page explains what that means and what it buys you.

A manuscript is not a document

The default model in word processors — Pages, Word, Google Docs — is the document: one long piece of text with optional headings. The model in tools like Scrivener is the binder: a tree of arbitrary text snippets that the writer organizes by hand. The model in Markdown-based tools like Ulysses or iA Writer is the file or sheet: a flat list, optionally grouped, with structure expressed through filenames or headings inside the text.

None of these are wrong. They are all reasonable choices for some kinds of writing. But none of them are manuscripts in the way that publishing actually defines a manuscript.

A manuscript has structural objects that exist whether or not the writing tool acknowledges them. There are scenes. There are chapters that contain scenes. There are parts that contain chapters. There is metadata at every level — point-of-view character, time setting, location, status. There are relationships across scenes that the writer carries in their head because the tool will not.

The .book format makes those structural objects explicit.

What’s inside a .book package

A .book file is a directory bundle, the same kind of structure macOS uses for .app and .pages files. It is not a single binary blob; it is a small filesystem you can open and inspect.

Inside, the manuscript is represented as a structured tree:

• Parts contain chapters
• Chapters contain scenes
• Scenes contain prose, plus structural metadata (POV character, location, time, draft status)

Every object has a stable identifier that survives renaming, reordering, and revision. Characters, locations, and other manuscript-wide entities are stored once and referenced from the scenes that use them, so renaming a character once changes every reference everywhere.

Drafts are content-addressed and revision-aware. The bundle tracks what changed between drafts without depending on an external version control system, though .book packages also play well with Git for writers who want one.

The format is open. The on-disk layout is plain JSON and text — readable, scriptable, and recoverable by hand if you ever need to. A full public specification of the format is in preparation and will be published under the Incipor GitHub organization as a separate reference document.

What that buys you

A document with a real structural model can do things a flat document cannot.

Continuity tracking that actually works. Because every scene knows which characters appear in it, an automated pass can flag the chapter where a character’s eye colour changes mid-novel, or the timeline contradiction where two scenes happen on the same Tuesday afternoon. This kind of editorial continuity check is the most common job indie authors pay developmental editors for. With a structural model, the tool can do the easy 80 percent of the job before the editor sees the manuscript.

Manuscript-wide reports, not document-wide stats. Word count is a useless metric in a flat document — a 90,000-word file with no scene awareness cannot tell you that your second act is shorter than your first, that one POV has half the page count of another, or that you have three consecutive chapters with no scene change. With scenes as first-class objects, all of these become trivial reports.

Export that respects structure. EPUB, PDF, manuscript-format Word, and Apple Books output all need to know where chapters begin, where scenes break, and which metadata to surface. A flat document has to be re-parsed every time. A .book package already knows.

Refactor without fear. Renaming a character across 300 pages of prose is a search-and-replace operation in a flat document, and the writer has to trust that there are no edge cases (a character named Mark whose name should change to Mike will rename every instance of mark the word). In a .book package, characters are referenced by ID, not by name. Renaming changes the entry in one place; every reference updates automatically and unambiguously.

What it does not do

The .book format is not a content management system. It does not replace Git for writers who already use it; it complements it. It does not lock your prose inside a proprietary container — you can export to plain Markdown, manuscript-format Word, EPUB, PDF, or Fountain at any time without losing your content. Only the structural metadata is .book-native, and that metadata is regenerable from a careful re-import.

It is also not a collaboration system. A .book package is single-author by design. Co-writing, beta reader workflows, and editor markup live elsewhere — the export to Word with tracked changes is the bridge to those workflows.

Why we built our own format

Most writing apps inherit their document model from the tool they replaced. Scrivener inherited a binder model from index cards on a corkboard. Ulysses inherited a sheet model from Markdown text editors. Pages inherited a document model from word processors going back to the 1980s.

We started Incipor by asking what a writing app would look like if the manuscript itself, not the document or the binder or the sheet, were the unit of work. The .book package is the answer. Every Incipor feature — Continuity Watch, Manuscript Report, Editorial Pass, Line Polish, Echo Finder — exists because the format makes it cheap to ask manuscript-wide questions that other tools have to recompute from a flat document each time.

The format is the foundation. Everything else is a consequence of it.