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, and build configurations for
producing multiple editions of the same manuscript. See
Conditional content.
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, with no limits.