Skip to content

Quickstart

This guide takes you from nothing to a finished PDF using the core-slim template — the everyday Keystone template. You'll create a project, add a chapter, and build.

Before you start

You need three tools. You do not install Pandoc or LaTeX — they live inside the Keystone image.

  • Docker — runs the engine
  • GNU Make — drives the build
  • Git — clones your project

On Windows, work inside WSL. Keystone expects Unix (LF) line endings and POSIX paths.

1. Create your project

Open the core-slim template on GitHub, click Use this template to create your own repository, then clone it:

git clone git@github.com:you/my-book.git
cd my-book

Not using GitHub? Download the template's source instead and start from those files — see Getting a template.

2. Name the project

Edit project.conf and set KEYSTONE_PROJECT to a short, lowercase name. This names the output files — it is not your book's title:

KEYSTONE_PROJECT=my-book

3. Set the essentials

Edit pandoc.yaml. At minimum set the title, author, and — for the default book target — a description:

title: My Book
author: Your Name
description: A short line about the book.

pandoc.yaml holds all book metadata and layout. See Book metadata for the full key reference and Targets to choose something other than book.

4. Write a chapter

Add Markdown files under manuscript/, one per chapter. Give each chapter a single top-level heading — don't number it yourself; Keystone numbers chapters during the build:

# The Beginning

It was a bright cold day in April, and the clocks were striking thirteen.

For a heading that shouldn't be numbered — a preface or appendix — add {.unnumbered} (# Preface {.unnumbered}); more in Manuscript & structure.

Images go in assets/ and are referenced by relative path: ![A caption](assets/cover.jpg).

5. Set the build order

publish.txt lists the manuscript files to include, in order — one path per line, relative to the project root. Lines starting with # are ignored, so you can comment a file out to drop it from a build:

manuscript/introduction.md
manuscript/chapter-1.md
# manuscript/chapter-2.md   (draft — excluded for now)

Only files under manuscript/ belong here; assets are pulled in automatically when your Markdown references them.

Order files on disk, too

Keystone imposes no structure inside manuscript/ — publish.txt alone decides the build order. But a common developer habit makes the folder easier to navigate: prefix filenames with a number (01-introduction.md, 02-chapter-one.md) so they sort into reading order in your editor and directory listings.

6. Build

make publish              # PDF (default)
make publish format=epub  # EPUB
make all                  # PDF, EPUB, and DOCX

Output lands in artifacts/, named <project>-<target>-<date>:

artifacts/
└── my-book-book-20260621.pdf

make help lists every target.

There's no live preview to wait on — you write in your Markdown editor and build to see the result, the way developers work. Builds are quick: EPUB and DOCX are near-instant, and a PDF takes seconds, not minutes — so rebuild as often as you like to nail the look. Day to day, authoring is just writing text, with the occasional rebuild to appreciate the work in progress.

Next steps

  • Project anatomy — what each file in your project does
  • Verifying your download — confirm your template and image are authentic
  • Writing — format dialogue, add a scene break, place a figure, and every other authoring task
  • Shortcuts — Keystone's styling API and your own project vocabulary