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. To link to a heading — and keep the link from silently breaking — see Cross-references.

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. To drop it from the contents too, add .unlisted — both classes are listed in Native styles. A heading shortcut can name the pair, as in # Preface {.front-matter}. (For no numbering anywhere — common for fiction and poetry — turn it off document-wide; 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. Numbering and the contents have per-format exceptions in EPUB and ODT — see Output formats.

To keep numbering but stop it at a given depth, set secnumdepth to the deepest heading level that should carry a number (# = level 1); headings below it read as unnumbered titles, the same depth in every format. It is the document-wide lever for "number chapters and sections, but not subsections".

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

Appendices

An appendix marker switches every chapter from it on to appendix numbering. The chapters re-letter (A, B, C…) and their subsections number A.1, A.2. The heading label localizes from your lang — the same machinery that labels ordinary chapters "Chapter". It's a one-shot marker: drop it once, where the appendices begin. On the article family, where # is a section, it re-letters those sections rather than chapters.

# Sources {.appendix}

# Data Tables

The marker rides the first appendix heading. Or put it in a div of its own — ::: appendix and ::: — in a dedicated zz-appendix.md you list in publish.txt, so you can reorder the appendix chapters freely. To change the enumerator from the default letters, set numbering (the reference lists the values):

::: {.appendix numbering="upper-roman"}
:::

Appendix numbering needs numbered headings — with numbersections: false there is nothing to re-letter.

This is PDF-only: appendix numbering has no equivalent in the other formats, so there the marker is ignored and the chapters render normally. If you need appendix labels in every format, bake the label into an unnumbered heading instead — # Appendix A — Sources {.unnumbered} — at the cost of hand-lettering and no automatic subsection numbering (see Unnumbered headings).