Skip to content

1.15 Books and Chapters

Jump to bottom
Frédéric Clavert edited this page Jul 20, 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, 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;
  • create, rename (double-click the title), reorder (arrows), and remove from the manuscript;
  • an unattached files section when relevant;
  • under each chapter, its internal headings — clicking one of them 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.

Book-wide tools

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

Tool What it does
Search the manuscript 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.
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.

Book settings

Four settings live in project.json and drive the export:

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.

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.

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