Choosing a template
You don't install Keystone directly — you start from a template. A template
is a ready-made project skeleton: the directory layout, a Makefile, the Docker
wiring, and the config files you fill in. It's what turns the Keystone engine
into something you can write a book in.
The templates that ship today run the same engine over the same manuscript. What differs is whether that engine is a sealed black box or sitting in your project for you to read and change, and whether a renderer for diagrams comes with it — the one thing that changes what a book comes out looking like.
core-slim |
core-diagrams |
core |
|
|---|---|---|---|
| Engine | Prebuilt image, out of sight | Prebuilt image, out of sight | Shipped in your project (.pandoc/) |
| First build | Fast — pulls the image | Slower — the second image carries a browser | Slower — builds the image locally |
Diagrams from a mermaid fence |
Wire it in yourself | Ready to write | Wire it in yourself |
| Customize the engine | No | No | Yes |
| Verify image signature | make verify |
make verify — engine and hook |
(you build it yourself) |
| Best for | Writing your book | Writing with diagrams in it | Understanding or customizing the engine |
How to choose
Start with core-slim. It's the everyday template: you write Markdown, edit
pandoc.yaml, and run make publish. The engine stays out of your way, builds
are fast, and you can verify the signed image you're pulling.
Take core-diagrams if your book has diagrams in it. It is core-slim plus
a renderer, so a plain mermaid fence becomes a figure —
Diagrams shows what you write. The renderer is a second
container that starts with your build, which is why it is a template of its own:
a book without diagrams shouldn't pay for one.
That renderer is an ordinary hook, and a hook belongs to no
one template. What core-diagrams gives you is the wiring already done.
Reach for core only when you need to see inside the engine or change it —
add a handler, adjust a filter, study how a build actually runs. It ships the
entire runtime in your project and builds the image
locally, so nothing is hidden and there's nothing to
reverse-engineer. The engine documents what you now have in
front of you, and how to change it.
Either way the authoring experience is the same: the Writing and Configuration sections of this manual apply unchanged to every one, and so do the pipeline a build follows and the sandbox it runs in.
Getting a template
The quickest start is GitHub's Use this template button on a template's repository, which gives you your own copy as a new repository. You don't need GitHub, though: download the repository's source (Code → Download ZIP, or any clone) and start from those files under whatever version control you prefer — or none. Git and a hosted repository are conventions Keystone leans on, not requirements.
The Keystone CLI will make this smoother still, scaffolding a new project without tying you to git or GitHub. Until it ships, using the template or downloading its source is how you begin.