Skip to content

Changelog

What each Keystone release changed, newest first. For how to move a project onto a newer release, see Upgrading your project.

Breaking: comes first where a release has one, covering anything that stops an existing project from building unchanged; each of its bullets names what to do about it. The other two groups say where a change landed — Engine: is how Keystone builds your book, Template: is the files your project owns, the ones you would merge by hand. The Unreleased section lists work that is merged and awaiting the next release.

Unreleased

v2.2.5 — 2026-07-24

Breaking:

  • Setting a metadata key the target owns now fails the build: documentclass, css, header-includes, keystone-justify, keystone-indent, keystone-fontsize-set, or keystone-required-fields. Remove them from pandoc.yaml and style through metadata and shortcuts instead. See Reserved keys and Reserved metadata key.

v2.2.4 — 2026-07-24

Breaking:

  • fontfamily accepts font-registry keys only; an arbitrary LaTeX font-package name no longer passes through. Register the font in fonts/fonts-registry.yaml to make it a valid key. An unrecognized value warns and falls back to latin-modern, and fails the build under warnings-as-errors. See Custom fonts and Unrecognized font family.
  • A cover-image, code-theme, bibliography, or csl path pointing outside the project directory now fails the build. Move the file into the project. Font paths in fonts/fonts-registry.yaml are exempt.

Engine:

  • toc-depth sets how many heading levels reach the table of contents, and applies identically in every output format. See Structure.
  • secnumdepth caps how many heading levels are numbered, in every format that numbers them. See Whether headings number at all.
  • toc and numbersections are now honored by EPUB, DOCX, and ODT — previously only the PDF respected a false.
  • linestretch sets line spacing in the PDF, validated as a positive number. See Line spacing.
  • colorlinks colors link text instead of boxing it, with linkcolor, urlcolor, citecolor, and toccolor taking #RRGGBB values. See Link colors.
  • monofont picks the font for code blocks and inline code, so code can use a wider Unicode range than the body font. See The code font.
  • fontsize is validated against the target's document class, and KOMA targets accept sizes the standard classes reject. An unsupported size snaps to the nearest allowed one. See Base font size.
  • New registry fonts: latin-modern-mono, latin-modern-math, noto-mono, and source-code-pro.
  • All three DejaVu families now embed in EPUB, retiring the path that relied on fonts installed on the reading device.
  • Math and symbol glyph coverage is broader, and the packages behind registered fonts are pinned.
  • An appendix div marks back matter, with configurable numbering. See Appendices.
  • A sym shortcut renders characters the body font lacks — ≫, ⩽, ∀ — in the shipped math face. See sym.
  • Aligned figures take an opt-in space-after attribute. See aligned-figure.
  • XeLaTeX shell-escape is locked off during PDF builds, so a manuscript cannot run commands through the typesetter. See Shell-escape is off.
  • Importing a document runs Pandoc sandboxed, which matters when the source is untrusted. See What to expect.
  • The image drops from 1.26 GB to 737 MB — it now carries only the font files the registry references, and rebuilds its TeX Live layer on pandoc/minimal.

Template:

  • pandoc.yaml gains toc-depth, secnumdepth, linestretch, colorlinks with its four colors, and monofont, and documents the new fontsize and fontfamily validation.
  • fonts/fonts-registry.yaml drops the command field — LaTeX command names are derived now.
  • make verify pins the cosign image it runs and matches the signing identity exactly rather than by substring.
  • NOTICE.md and the bundled font licenses cover the newly registered fonts.

v2.2.3 — 2026-07-05

Engine:

  • A div or span class outside Keystone's vocabulary is now flagged instead of passing through silently. See Unrecognized class.
  • A shortcut that omits a required field fails against the shortcut's own interface, naming the field. See Missing required field.
  • Build failures name the phase they occurred in, and every diagnostic follows one format. See Errors & checks.

Template:

  • project.conf gains KEYSTONE_WARNINGS_AS_ERRORS, which turns any warning into a build failure that writes no artifact — for CI and release builds. make publish strict=true overrides it per run.

v2.2.2 — 2026-06-27

Breaking:

  • Math the target format cannot represent now fails the build instead of being dropped silently from the output. Simplify the expression, or restrict it to a format that supports it. See Math that can't convert.

Engine:

v2.2.1 — 2026-06-21

The release the public manual was first written for.

Template:

  • The comments in pandoc.yaml and shortcuts.yaml point at the manual for detail instead of describing everything in place.

v2.2.0 — 2026-06-20

Engine:

  • Running headers and footers can read author-declared marks, for content no heading tracks — the current poem in an anthology, say. Declare the names in pandoc.yaml, set them inline with .set, and read them as {name} placeholders. See Author-declared marks.
  • An undeclared mark warns instead of silently resolving to nothing. See Undeclared mark.
  • {chapter} and {section} placeholders resolve correctly for unnumbered headings, and an unnumbered div marks a heading as excluded from numbering.
  • Blank filler pages in PDF builds carry no running header, matching the KOMA targets.

Template:

  • pandoc.yaml gains marks for declaring running-header mark names.

v2.1.0 — 2026-06-15

The release where Keystone's shape settled — most of what the manual describes today arrived here.

Breaking:

  • footer-copyright is gone. Set footer-text (or header-text) instead, which takes any content you want in each slot. See Header and footer text.
  • The book, article, and report targets no longer draw a rule under the running header. Set header-rule: enabled to restore it. KOMA targets are unaffected. See The header rule.

Engine:

  • Running headers and footers replace the old copyright footer, with separate recto and verso text, configurable page-number position, and an optional rule above the header. See Recto and verso.
  • Header and footer text takes dynamic placeholders — {title}, {author}, {page}, {chapter}, {section}. See Placeholders.
  • KOMA-Script targets scrbook, scrreprt, and scrartcl join book, report, and article. See Standard vs KOMA.
  • Bibliographies and citations work through Pandoc's citeproc, with a bibliography file and a csl style. See Citations.
  • keystone-note-placement switches footnotes to endnotes.
  • ifdef and ifndef divs include or exclude content by build configuration, so one manuscript can produce several editions. See The two primitives.
  • Ornamental fonts ship for decorative fiction elements — fleurons, chapter openers, manicules. See Decorative ornaments.
  • Ragged-right text keeps hyphenation instead of dropping it.
  • The image pins a dated TeX Live snapshot, so a given version rebuilds identically.
  • Existing DOCX and ODT documents can be imported into a manuscript. See Convert a document.

Template:

  • pandoc.yaml gains header-text, header-text-recto, header-text-verso, footer-text, footer-text-recto, footer-text-verso, page-number-position, header-rule, bibliography, csl, and link-citations.
  • project.conf declares build configurations as KEYSTONE_DEFINE_<name>="symbol …", and KEYSTONE_USING picks the one to build when using= is omitted.

v2.0.7 — 2026-04-26

Engine:

  • PDF metadata carries keywords and a subject, embedded as XMP so cataloguing tools can read them. xmp-metadata opts out. See Summary fields.
  • The dialog shortcut validates its style attribute, and styled dialogue blocks lay out correctly in both PDF and EPUB. See Wrapped turns.

Template:

  • pandoc.yaml gains subject and xmp-metadata.

v2.0.6 — 2026-04-26

Engine:

  • A security update to a tool bundled in the image. Nothing changes for your manuscript.

v2.0.5 — 2026-03-30

Engine:

  • An epigraph's attribution sits inside the quote rather than after it, so it aligns to the quote's indent and spaces correctly. See Epigraphs.
  • The content placeholder is available by name as a slot shortcut, for use in your own definitions. See Naming the content slot.

v2.0.4 — 2026-03-30

Engine:

  • Keyword metadata survives on Pandoc 3.9.0.2 and later, which changed how quoting reaches the PDF.

v2.0.3 — 2026-03-30

Breaking:

  • An epigraph's attribution moves from a dash-prefixed final paragraph to a source="Author" attribute. See Epigraphs.

Engine:

  • A pullquote shortcut sets a passage off from the body text. See Pull quotes.
  • A vspace div inserts explicit vertical space, and a no-indent div suppresses paragraph indentation for a stretch. See Vertical space.
  • A shortcut definition can place the author's content explicitly, so a shortcut wraps that content instead of only preceding it. See Body injection.

v2.0.2 — 2026-03-15

Engine:

  • Dialogue lines no longer overlap when indentation control is on.

v2.0.1 — 2026-03-15

Breaking:

  • The align shortcut renames its align= attribute to style=, and no longer applies italic or bold — compose it with the font shortcut instead.
  • The aside shortcut drops font-family=. Nest a .font div inside the callout.
  • The figure shortcut drops align=. Use the figure-center, figure-left, or figure-right shortcuts, which align in every format including DOCX and ODT. See Positioning.

Engine:

  • indent-control sets first-line paragraph indentation. See Suppressing indentation.
  • justify-control reaches DOCX and ODT as well.
  • An aligned-figure shortcut places a figure and its alignment together. See Reusable presets.
  • Shortcuts declare an interface, so an attribute a shortcut accepts is named explicitly and routed to the handler underneath. See The interface.
  • System shortcuts are the supported way to reach a handler; handler classes sit behind the ks- namespace. See Build on the stable layer.
  • Figure captions are constrained to the width of the image.
  • Alignment on a block-level child works in EPUB.

Template:

  • pandoc.yaml gains indent-control and justify-control.
  • shortcuts.yaml documents the interface: form, and a shortcut that shadows a system shortcut takes precedence — delete the entry to restore the default.

v2.0.0 — 2026-03-01

Keystone became multi-format here, and this is the largest upgrade it has asked authors to make.

Breaking:

  • chapters/ and appendix/ are consolidated into a single manuscript/ directory. See manuscript.
  • The target is set by target: in pandoc.yaml rather than passed as make publish target=…. See The six targets.
  • The built-in poem-date style is retired; compose the same result from the align and font shortcuts.

Engine:

  • DOCX and ODT join PDF and EPUB as output formats. Each ships a reference document carrying its styles. See DOCX and ODT.
  • article and report targets join book. See The six targets.
  • Shortcuts arrive: named style aliases for divs and spans, defined in shortcuts.yaml, composable and nestable. See How you use them.
  • New shortcuts — aside for typed callouts, dropcap for chapter-opening initials, epigraph for opening quotations, scene-break for decorative separators, figure for styled images, align for alignment, multicol for two-column layout, and container for plain grouping.
  • Code blocks are styled in PDF and EPUB, with code-theme selecting the highlighting. See Syntax-highlighting themes.
  • epub-only, docx-only, and odt-only divs include content in one format only. See Targeting a format.
  • A draft watermark prints across every PDF page, sized by draft-scale.
  • A project can supply its own font files. See Custom fonts.

Template:

  • pandoc.yaml gains target, toc, numbersections, abstract, classoption, code-theme, draft, and draft-scale.
  • shortcuts.yaml is a new file, where a project defines its own style vocabulary.
  • The compose files are hardened, and the core-slim image tag is pinned to the release during assembly.

v1.8.6 — 2026-02-22

Engine:

  • Div styling reaches EPUB chapter pages, not only the title page.

v1.8.5 — 2026-02-22

Engine:

  • Fonts are embedded in EPUB output, so a book renders as designed on a device that lacks them. See Built-in fonts.
  • TeX Gyre and EB Garamond families ship in the image.

Template:

  • Locally built images are tagged :local rather than taking :latest.

v1.8.4 — 2026-02-20

Engine:

  • fontfamily and fontsize can be overridden per element, against a unified font registry. See Local overrides with font.
  • The latex-only handler works on spans as well as divs.

Template:

  • The drafts/ and research/ scaffolding directories are gone — keep working notes wherever suits you.
  • The output directory is created on demand instead of being tracked empty.

v1.8.3 — 2026-02-18

No changes to the engine or templates.

v1.8.2 — 2026-02-18

Template:

  • verify.sh spells out the limits of what a signature check proves.

v1.8.1 — 2026-02-17

Template:

  • Assembled templates ship a GPG-signed checksum manifest, so you can confirm what you downloaded is what was published. See The template.
  • make verify checks the runtime image's signature.
  • make with no target prints the help.

v1.8.0 — 2026-02-15

Engine:

  • Released images are signed and carry an SBOM, and every release is scanned for known vulnerabilities. See The runtime image.

v1.7.5 — 2026-02-15

Breaking:

  • make sample is gone, and the sample book no longer ships inside the image. Templates start empty.

v1.7.4 — 2026-02-14

Engine:

  • Publishing containers run as a non-root user.
  • Dialogue and poem-date styling handle inline formatting inside their content.

Template:

  • fontsize defaults to 11pt, matching what the targets actually used.

v1.7.3 — 2026-02-14

Engine:

  • Published image manifests carry their annotations correctly.

v1.7.2 — 2026-02-14

Engine:

  • Multi-platform images carry manifest-level annotations, so registries show the source and license.

v1.7.1 — 2026-02-14

Engine:

  • Div handling runs in a single pass instead of one filter per handler.

v1.7.0 — 2026-02-13

Template:

  • The compose file pulls the image from ghcr.io/knight-owl-dev/keystone, its new home.

v1.6.1 — 2026-02-12

Engine:

  • The image carries a Keystone version label.

v1.6.0 — 2026-02-12

Engine:

  • An empty cover-image no longer crashes EPUB builds.

v1.5.0 — 2026-02-08

Breaking:

  • project.conf replaces .env for project settings, and pandoc.yaml is the sole source of book metadata — values no longer come from the environment. See project.conf.

v1.0.2 — 2026-02-07

Engine:

  • Release builds cache against the current image.

v1.0.1 — 2026-02-07

Engine:

  • Book metadata is read from user-metadata.yaml in preference to the environment.

v1.0.0 — 2025-06-22

The first tagged release. Keystone could take a Markdown manuscript and produce a PDF and an EPUB through Pandoc, XeLaTeX, and a pinned Docker image, driven by make.

Before v1.0.0

Keystone began on 2025-04-05. The structure was different — one repository, no templates to fork, nothing published for anyone else to use — but over the 119 commits leading to v1.0.0 the outlines of what it became were already there.

Milestones from that stretch, for the record:

  • April 2025 — the publishing pipeline: Pandoc and XeLaTeX in Docker, driven by make, with base LaTeX styling and a pinned Pandoc version.
  • April 2025 — the first div handlers, dialog and latex-only, and with them the idea that a manuscript could carry styling instructions Pandoc alone does not understand.
  • April 2025 — DOCX output and document import, so a manuscript could arrive from somewhere else and leave in more than one format.
  • April 2025 — the template model: a canonical repository syncing assembled templates to public repositories, and the first slim variant.
  • May 2025 — pagebreak and poem-date handlers, and book metadata moving out of environment variables into YAML.

None of it was published for anyone else to use. The first image reached a registry in June 2025, as v1.0.0.