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-project/
├── 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 behavior
├── publish.txt          # Which manuscript files to include, in order
├── shortcuts.yaml       # Your custom styling vocabulary
├── artifacts/           # Build output
├── Makefile             # Build commands — don't edit
├── .docker/             # Container wiring — don't edit
├── .keystone/           # Template 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 (![A caption](assets/photo.jpg)); 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 rather than book content: the project name that goes on output files, Docker naming, strict builds, build progress, build configurations, and hook limits. The Project settings reference covers every key.

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. Every template ships the same one: comments to start from, no entries. See Writing your own shortcuts.

fonts/

Optional. Drop .otf files here, with the license text each came with, 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. artifacts/ holds everything generated, so it is ignored by git and emptied by make clean. .licenses/ and NOTICE.md carry the attributions Keystone and its dependencies require — keep them.

A template that runs the engine from a prebuilt image stops here. One that ships the engine source carries it in .pandoc/, for authors who want to read or change it, and one that wires a hook carries its service in .docker/.