# Writing a Book — Chapters Guide

*New in RC3.*

Until RC2, a "book" project was a label: your whole manuscript lived in a
single `document.md`, and the export produced a PDF without real chapters.
RC3 turns it into a working feature — a manuscript in several files, with a
navigator, an outline, book-wide tools and an export that produces an actual
book.

---

## The model: one file per chapter

A book project has **no `document.md`**. Its text lives in markdown files —
typically under `chapters/` — and `project.json` holds the **manifest** that
orders them:

```json
{
  "type": "book",
  "chapters": [
    { "id": "c1", "title": "Introduction",
      "filePath": "chapters/01-introduction.md", "order": 0, "kind": "chapter" }
  ]
}
```

Two consequences worth knowing:

- **Your chapters are ordinary markdown files.** You can open them in any
  editor, put them under version control, e-mail one to a colleague.
- **The manifest decides the order**, not the filename. The numeric prefix
  (`01-`) is there for you, when you look at the folder outside ClioDeck.

### The `#` heading is the chapter title

Each chapter file starts with a level-1 heading — that heading *is* the
chapter title at export time. Inside a chapter, use `##` for sections.

### Nothing is ever lost

ClioDeck reconciles the manifest with what is actually on disk:

- a file listed in the manifest but missing from disk is **flagged**
  (*File not found*), never silently dropped;
- a `.md` file found in the project but absent from the manifest appears as
  **unattached**, with a button to attach it.

So if you drop a chapter into the folder from the Finder, ClioDeck notices
and offers to add it. If you delete one by accident, the entry stays visible
instead of vanishing.

---

## The chapter navigator

Open a book project and a panel appears to the left of the editor:

- the **ordered list of chapters**, numbered, current one highlighted;
- **Add a chapter**, **Rename** (or double-click the title), **Move up** /
  **Move down**, and **Remove from manuscript (the file is kept)**;
- an **unattached files** section when relevant ("Found in the project but
  missing from the manuscript"), with an **Attach to manuscript** button;
- an **Outline** toggle under each chapter, listing its internal headings —
  clicking one jumps there, even in a chapter that isn't currently open.

**Removing a chapter never deletes its file.** It leaves the manifest, and
reappears immediately in "unattached files". The confirmation dialog says so.

### Switching chapters costs nothing

Moving from one chapter to another preserves your undo history, cursor
position and scroll. Come back to chapter 2 and `Cmd/Ctrl+Z` still undoes
the sentence you typed before leaving it.

One deliberate exception: **pending AI proposals expire** when you switch
chapters. They are logged as expired rather than resurrected — though the
chapter attached to that log entry is currently wrong; see
[The Editor](./1.16-The-Editor.md#when-the-assistant-writes).

---

## Book-wide tools

These act on the *whole* manuscript, not just the open chapter:

| Tool | What it does |
|---|---|
| **Search the book** | Find a term across every chapter; results are grouped by chapter, and clicking one opens the right chapter at the right place. Accent-insensitive: `eglise` finds `église`. A chapter with very many hits shows only the first ones, and says so. |
| **Renumber footnotes** | Renumbers notes across the book, in manifest order. Atomic: either every file is rewritten or none is. A chapter already correct is left untouched. |
| **Check citations** | Lists citation keys missing from your bibliography, telling you which chapter each one is in. Citations inside code blocks are ignored. |
| **Statistics** | The status bar shows the current chapter *and* the whole-book total. |

> The open chapter is always read from the live editor, so your unsaved
> keystrokes are counted, searched and renumbered like the rest.

> **⚠️ Real bug, verified against code:** "Atomic" above means atomic
> against *its own* failures — the rollback restores every already-written
> chapter if a later write in the same run fails. **Since RC4 the lock works
> both ways**: an export refuses to start while a renumbering is running,
> and a renumbering refuses to start while an export is assembling. Until
> RC4 only the first direction was checked, so triggering a renumber during
> an export could rewrite the manuscript underneath it.

---

## Book settings

Four settings live in `project.json`'s `book` key and drive the export.
**Since RC4 they have a dialog** — the book settings modal, reachable from
the project panel. Before RC4 they could only be changed by hand-editing
`project.json`, which nothing in the app told you was possible.

| Setting | Options | Default |
|---|---|---|
| **Note style** | footnotes · endnotes per chapter · endnotes at the end of the book | footnotes |
| **Note numbering** | continuous across the book · restarting in each chapter | continuous |
| **Bibliography** | one at the end · one per chapter | one at the end |
| **Numbering** | numbered chapters, unnumbered sections | on / off |

A per-chapter bibliography runs the citation engine once per chapter
(roughly one second per chapter) and keeps your CSL style — once #24 makes
this reachable.

---

## Front matter and back matter

A manifest entry has a `kind`:

- `chapter` — the body of the book, numbered;
- `front` — preface, dedication, acknowledgements (placed before the body);
- `back` — appendices, sources, index (placed after).

`abstract.md`, created with every book project, is your **back-cover
summary**: it is rendered as the abstract of the exported document.

---

## Exporting

**PDF** produces a real book: numbered chapters, table of contents, front
and back matter in place, notes and bibliography following your settings.

**Word** produces one section per chapter with a page break, a table of
contents and proper heading styles. Until RC4, a book exported with a
bibliography attached and Pandoc installed — the normal setup for a book
with citations — came out empty of chapter content; the manuscript is now
assembled before the export branches, on every path.

Since RC4 the Word export also honours **chapter numbering and document
structure** from the book settings. Note *style* (footnotes vs endnotes)
remains PDF/LaTeX only: it relies on LaTeX commands that have no equivalent
in a `.docx`.

Both offer a **scope**: the whole book, or **this chapter only** — handy for
sending a single chapter to a colleague or submitting a contribution to an
edited volume.

### One thing to know about footnotes

If chapter 1 and chapter 2 both contain a note called `[^1]`, a naive
assembly makes both of them display the *same* text — the first chapter's
note silently disappears. ClioDeck renames note identifiers per chapter when
assembling, so this cannot happen. You never see it; you just never lose a
note.

---

## What is not there yet

- An **index** (`\index{}`) and typed **cross-references** ("see chapter 3")
  are not implemented.
- The **Word** export does not yet honour the endnote settings; those drive
  the LaTeX/PDF route only.

---

## See also

- [The Editor](./1.16-The-Editor.md) — live rendering, footnotes, citations.
- [Word Templates](./1.3-Guide-for-Using-Word-Templates.md)
- [RC3 Release Notes](./3.3-RC3-Release-Notes.md)