Skip to content

core — the full template

core ships the entire Keystone engine inside your project and builds the Docker image locally. It exists for authors who want to understand the engine or customize it — without reverse-engineering anything. Everything that core-slim keeps in a prebuilt image is here in plain sight, under .pandoc/.

That openness is deliberate. Your time matters — and so does ours; handing you the engine to read and change beats leaving you to reverse-engineer it. That's the open-source bargain, and it's why core exists at all.

Get it from the core template repository. The authoring workflow is identical to core-slim — the Writing and Configuration sections apply unchanged.

What's different

Alongside the usual project files, core includes:

  • .pandoc/ — the engine: publish.sh, import.sh, the Lua filters, the handler directories, and the metadata bundles.
  • A Dockerfile — so the image is built from source rather than pulled.

The one extra command is make image, which builds that image; the publish targets depend on it:

make image                # build the engine image locally
make publish              # build a PDF (builds the image first if needed)
make all                  # PDF, EPUB, and DOCX
make import artifact=draft.docx
make clean
make help

There's no make verify — you build the image yourself, so there's no published signature to check.

The engine

Because the runtime is in your project, you can read and change it. The engine guide documents how it works and where the seams are:

  • Build pipeline — what happens between make publish and a finished file.
  • Handlers — how a ::: name block becomes formatted output, and the contract a handler honors.
  • Format integration — how output is produced for LaTeX, EPUB, and DOCX/ODT.
  • Customizing — adding a handler or filter to your copy.

If you find yourself heavily rewriting the engine, you've crossed from using Keystone into forking it — which is a legitimate thing to do, and core is the starting point for it.

When a new release lands, Upgrading your project covers moving a core project onto it; an AI assistant can run the AI-assisted procedure for you (it stops and hands back if you've customized the engine).