Skip to content

Publishing your book

Keystone's output is publication-ready: the PDF is a print-quality file and the EPUB is a standards-compliant e-book. When the writing is done, the last step is getting those files to readers — Keystone produces the artifacts, and a publishing platform handles printing and distribution.

Which file goes where

  • PDF → print. Print-on-demand (POD) services and offset printers take a PDF. Match your page setup to the printer's spec first — trim size via papersize and binding margins via geometry (see Book metadata).
  • EPUB → e-book stores and readers. EPUB is what e-book retailers and reading apps expect. Set a cover with cover-image so it appears in the store listing and the reader's library.

These platforms turn your files into a printed book, an e-book listing, or both. Common starting points:

  • Lulu — print-on-demand and distribution.
  • Amazon KDP — print and Kindle on Amazon.
  • IngramSpark — print distribution to retailers and libraries.
  • Draft2Digital — e-book distribution across multiple stores.

Keystone doesn't endorse any of these. Each sets its own specs for trim size, bleed (art that extends past the trim edge), margins, and metadata — read theirs and match yours in pandoc.yaml.

Before you upload

A short checklist for a first book:

  • Pick a trim size and set papersize / geometry to match the platform's template.
  • Add a cover. cover-image covers the EPUB; print covers are usually a separate wraparound file the platform builds to your page count.
  • Get an ISBN if you want retail distribution — some platforms provide one free.
  • Proof the PDF at full size, and open the EPUB in a couple of readers to check how it reflows.
  • Fill in your metadata — title, author, description, and keywords all carry into the files (see Book metadata).

Strict builds for CI and release

While you're drafting, Keystone prints warnings — a mistyped attribute, an unrecognized placeholder, a missing font — and keeps going, so you always get something to look at. For the build you actually publish, you usually want the opposite: a warning should stop the line, not ship.

Set KEYSTONE_WARNINGS_AS_ERRORS=true to make any warning fail the build and write no new file — including structural slips Pandoc catches, like a fenced div you forgot to close. Turn it on in project.conf for release builds, or run make publish strict=true in CI to override the project.conf value without editing it — so automated builds stay strict while local drafts stay lenient.

The file you built is the file you publish — there's no separate export step.