Skip to content

Build pipeline

When you run make publish, a lot happens inside the container. This is the path from your source to a finished artifact. It applies to every template — in core you can read every piece of it under .pandoc/.

From make to artifact

  1. make publish runs the engine's publish.sh inside the Keystone image, with your manuscript/, assets/, fonts/, and config mounted in.
  2. publish.sh reads publish.txt, merges the system and user shortcuts, resolves metadata, and invokes Pandoc on the listed manuscript files, in order, with the right options for the requested format.
  3. Pandoc concatenates those files and parses the Markdown into its document model, then runs Keystone's Lua filters over it (below).
  4. Pandoc's writer for the format emits the result — XeLaTeX to PDF, the EPUB archive, or a DOCX/ODT built from a styled reference document.
  5. The artifact lands in artifacts/, named <project>-<target>[-<edition>]-<date> (the edition segment is set by using=).

The Lua filters

The heart of the engine is a chain of Lua filters, run in this order. Order matters — each builds on the output of the ones before:

  1. hooks.lua — hands each code block a hook claims to that hook and splices back what it returns. Present only when a hook is wired; first, because what comes back is author-level markup that the rest of the chain still has to see.
  2. shortcuts.lua — expands shortcut names into handler classes and attributes, so everything downstream sees plain handler elements. System shortcuts ship in the image; your shortcuts.yaml layers on top. See The shortcut system.
  3. keystone.lua — validates and enriches metadata (required fields per target, date, cover image, draft watermark, code theme) and injects the font and style definitions for the format.
  4. divs.lua — the dispatcher. It routes every fenced div and span to its handler and emits format-specific output. See Handlers.
  5. page-furniture.lua — composes the PDF running headers, footers, and page numbers from your metadata, resolving placeholders like {chapter}. It runs after the handler filters so any handlers inside header text have already rendered.
  6. math-check.lua — the guardrail. Stops the build (naming the equation) when one can't convert to your target format, instead of leaking raw LaTeX into the output. See Mathematics.

The EPUB pre-scan

EPUB embeds only the fonts your book actually uses, and Pandoc needs that list before the main run. For EPUB builds, publish.sh does a quick pre-scan pass first — running hooks, expanding shortcuts, and walking the document to find referenced font families — then embeds exactly those fonts in the real build. Other formats skip this step. It is a second Pandoc run, which is why a hook is asked to describe itself twice for EPUB.

Where it lives

In core, all of this is in your project under .pandoc/: publish.sh and import.sh, the filters/ directory (the Lua filters and the per-handler directories under filters/divs/), and metadata/ (the target bundles). In core-slim the same files live inside the prebuilt image. To change any of it, use core and see Customizing.