Project anatomy
A Keystone project is a small, version-controlled directory. Most of it is yours to edit; a few files belong to the engine. This page is the map.
my-book/
├── manuscript/ # Your prose — one Markdown file per chapter
├── assets/ # Images and cover art
├── fonts/ # Custom fonts (optional)
│ └── fonts-registry.yaml
├── pandoc.yaml # Book metadata and layout
├── project.conf # Project name, Docker naming, build configurations
├── publish.txt # Which manuscript files to include, in order
├── shortcuts.yaml # Your custom styling vocabulary
├── artifacts/ # Build output (generated)
├── Makefile # Build commands — don't edit
├── .docker/ # Container wiring — don't edit
├── .keystone/ # Release metadata (checksums, sync info) — don't edit
├── .licenses/ # License texts — Keystone's and its dependencies'
└── NOTICE.md # Attributions
What you edit
manuscript/
Your book's content, as Markdown. Keep one file per chapter or section — it
keeps diffs small and reordering trivial. Only manuscript/ and assets/ are
read by the build.
publish.txt
The build order. It lists the manuscript/ files to compile, one path per line,
top to bottom. Reorder lines to rearrange chapters; prefix a line with # to
drop a file from the build without deleting it. See
Manuscript & structure.
assets/
Images, cover art, and other media. Reference them from Markdown by relative
path (); referenced assets are bundled into the
build automatically.
pandoc.yaml
Everything about how the book looks and what metadata it carries — title, author, target, fonts, page layout, citations, headers and footers. This is the single most important file to learn; the Book metadata reference walks through every key.
project.conf
Operational settings, not book content: the project name (KEYSTONE_PROJECT,
used in output filenames), Docker naming, build configurations for producing
multiple editions of the same manuscript (see
Conditional content), and
KEYSTONE_WARNINGS_AS_ERRORS for strict builds (see
Publishing your book).
shortcuts.yaml
Your project's styling vocabulary, layered on top of Keystone's built-in
shortcuts — how you keep your markup DRY. Define a name like garamond once and
reuse it throughout the manuscript; change it in one place and every use follows.
Empty by default — see Writing your own shortcuts.
fonts/
Optional. Drop .otf files here and register them in fonts-registry.yaml to
use typefaces beyond the built-in set. See Typography & fonts.
What the engine owns
Makefile, .docker/, and .keystone/ are the build machinery and release
metadata. You run make; you don't edit these. .licenses/ and NOTICE.md
carry the attributions Keystone and its dependencies require — keep them.
The core-slim template stops here: the engine itself lives in a prebuilt
image, out of your way. The core template additionally ships the engine source
(.pandoc/) for authors who want to customize it — see Templates.
Your repo, your structure
Keystone recognizes only a few conventional folders — manuscript/,
assets/, fonts/. The rest of the repository is yours. Add as many folders
as your project wants and shape them however you work: a novelist can keep a
full worldbuilding bible — characters, timelines, maps; an academic, a
research tree of sources and notes. None of it affects the build, and all of
it is version-controlled alongside your prose — your whole body of work in one
place, organized your way.