Skip to content

Overriding a reserved key

Some keys belong to the layout your target selects rather than to you: anything starting with keystone-, plus a few standard Pandoc keys that carry the build's wiring. Set one in pandoc.yaml and the build stops while resolving configuration, naming the key.

What it looks like

Bringing your own stylesheet by setting css:

# pandoc.yaml
css:
  - assets/my-styles.css

ERROR: pandoc.yaml overrides Keystone-owned metadata
  css
  These keys are owned by the target and wire the build.
  Remove them from pandoc.yaml.
  See https://keystone.knight-owl.dev/errors/reserved-metadata-key/

Override more than one and the message lists each:

ERROR: pandoc.yaml overrides Keystone-owned metadata
  documentclass
  header-includes
  These keys are owned by the target and wire the build.
  Remove them from pandoc.yaml.
  See https://keystone.knight-owl.dev/errors/reserved-metadata-key/

A keystone- key adds a sentence naming the rule:

ERROR: pandoc.yaml overrides Keystone-owned metadata
  keystone-note-placement
  These keys are owned by the target and wire the build. The keystone- prefix is
  reserved for target metadata.
  Remove them from pandoc.yaml.
  See https://keystone.knight-owl.dev/errors/reserved-metadata-key/

What it means

css and header-includes pull in the core stylesheet and LaTeX preamble; documentclass is the class the target owns; the keystone- prefix marks everything else a target declares. Pandoc reads pandoc.yaml last, so a value there wins — overriding one drops that wiring and ships broken output or fails with an opaque LaTeX error. Keystone rejects it up front. Presence alone triggers the error: an empty css: still counts.

Switch to the counterpart, or remove the key

Some reserved keys have an author-facing counterpart, and its name is not always the bare key: keystone-note-placement pairs with note-placement, keystone-justify and keystone-indent with justify-control and indent-control (see Book metadata). Switching keeps your setting; deleting reverts it to the target's default.

A key with no counterpart comes out. Your layout is chosen with target (see Targets), and Reserved keys spells out what is owned.

Styling without css

There is no author stylesheet hook. Style through the levers you do have: metadata for the book's overall look — fontfamily, fontsize, linestretch, the link colors, code-theme (see Typography) — and shortcuts for styling specific content, which compose into reusable styled blocks.

  • Missing or invalid metadata — the other stop while resolving configuration: a field the target requires, an unknown target, or a value Keystone can't interpret.