Skip to content

Manuscript & structure

Your book is a set of Markdown files under manuscript/, assembled in the order you list them. This page covers how to organize those files and how headings become chapters.

One file per chapter

Keep each chapter or major section in its own file. Nothing forces this, but it keeps diffs small, makes reordering a one-line change, and lets you set a draft aside without touching the rest:

manuscript/
├── introduction.md
├── chapter-01.md
├── chapter-02.md
└── appendix-a.md

Only manuscript/ and assets/ feed the build. You can keep drafts/, research/, or notes/ folders alongside them — they're ignored.

Build order: publish.txt

publish.txt is the spine. It lists the manuscript files to compile, one path per line, in reading order. The first line is the first chapter:

manuscript/introduction.md
manuscript/chapter-01.md
manuscript/chapter-02.md
manuscript/appendix-a.md

Reorder lines to rearrange chapters. Prefix a line with # to exclude a file from the build without deleting it — handy for drafts:

manuscript/chapter-02.md
# manuscript/chapter-03.md   (still drafting)
manuscript/chapter-04.md

Files are concatenated in this order before Pandoc runs, so headings, footnotes, and cross-references all resolve across the whole book as if it were one document.

Organizing the folder

Keystone imposes no structure inside manuscript/ — publish.txt is the single source of truth for what's included and in what order, so the layout on disk is yours to arrange however helps you work. Two developer habits pay off:

  • Number your filenames. Prefixing with 01-, 02-, … sorts files into reading order in your editor and in directory listings, mirroring the order publish.txt builds them — so the folder reads the way the book does.
  • Group parts in subdirectories. publish.txt paths can point into subfolders (manuscript/part-1/chapter-01.md), so a long book can be split into parts on disk without changing a thing about the output.

Because publish.txt drives the build, none of this is load-bearing — rename or reshuffle freely; only the paths listed there matter.

Headings become structure

A single # heading is a chapter (or, for the article target, a section); ## and deeper nest beneath it. Write the title only — don't number it yourself. Keystone numbers headings during the build, controlled by numbersections in pandoc.yaml:

# The Lighthouse

## Approaching the Coast

This renders as "Chapter 1 — The Lighthouse" with "1.1 Approaching the Coast" beneath it. Because numbers are applied at build time, renumbering is automatic when you reorder publish.txt.

Unnumbered headings

Mark any heading that shouldn't carry a number with {.unnumbered}. The obvious cases are front and back matter — a preface, a dedication, an appendix — but it's just as useful anywhere a number would read wrong: a poem title that's structurally a section, a chapter you'd rather title than number.

# Preface {.unnumbered}

# Appendix A: Sources {.unnumbered}

The heading keeps its place in the flow and the table of contents; it just isn't numbered. (If you want no numbering anywhere — common for fiction and poetry — turn it off document-wide instead of marking every heading; see below.)

Whether headings number at all

numbersections: true (the default) numbers headings; set it to false to drop numbering across the whole book. This is the right lever for genres that conventionally carry no numbers at all — much fiction, and poetry collections where a number on a poem title looks out of place — rather than marking every heading {.unnumbered}. The table of contents (toc: true) and its presence are likewise controlled from pandoc.yaml — see Book metadata.

The chapter/section split itself comes from the target: book and report treat # as a chapter; article treats it as a section. See Targets.