Skip to content

1.15 Books and Chapters

Jump to bottom
Frédéric Clavert edited this page Jul 24, 2026 · 7 revisions

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:

{
  "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.

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. It does not guard against an export starting while the renumber loop is still mid-way through: nothing disables the export entry points or the renumber button while the loop runs. Trigger an export in that narrow window and it can assemble a manuscript with some chapters already renumbered and others not, silently. See issue #30.

Book settings

Four settings live in project.json's book key and drive the export — but none of them have a UI today. Every book project silently gets the defaults below; changing any of them means hand-editing project.json directly, which nothing in the app tells you is possible. Filed as issue #24.

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 — except when a bibliography is attached with Pandoc installed and no citation engine requested, the normal setup for a book with citations, where the export currently comes out empty of chapter content entirely. See the warning on the Word Templates guide and issue #19. PDF export is unaffected — it assembles the manuscript on every path.

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

Clone this wiki locally