Skip to content

Book metadata

pandoc.yaml holds everything about how your book looks and what metadata it carries. This page is the complete key reference, grouped by purpose. The file ships fully commented — this is the index to it.

Keys with a default can be omitted. Many are explained in depth in their own guide; this page links out rather than repeating them.

Identity

Key Default Notes
title — The book title (cover and metadata).
subtitle — Optional subtitle.
author — Author or organization; comma-separate multiple.
date auto auto (build date), disabled, or literal text.
lang en-US BCP-47 language code; sets hyphenation and the auto-generated labels — the TOC title ("Contents"), the "Chapter" prefix, and the like.
keywords — A list of keywords for the document metadata.

title and author are required for every target.

Summary fields

These feed the EPUB description and the PDF subject. Which one you set depends on the target (see Targets):

Key Notes
description Required for book; the short blurb. EPUB dc:description and PDF subject.
abstract Required for article/report; bridges into description and subject.
subject Optional override for the PDF subject alone; defaults to mirroring description.

Structure

Key Default Notes
target book The document class. See Targets.
toc true Generate a table of contents. EPUB keeps its reader navigation regardless — see Output formats.
toc-depth 3 Heading levels shown in the TOC (# = level 1); the same depth in every format.
numbersections true Number headings; exempt one with {.unnumbered}. No effect in ODT — see Output formats.
secnumdepth (unset) Deepest heading level that is numbered (# = level 1); deeper headings are unnumbered, identically in every format. Unset numbers all levels.

See Manuscript & structure for headings and numbering.

Body text

Key Default Notes
fontfamily latin-modern Document body font; any registry key. See Typography.
monofont latin-modern-mono Code/monospace font; any registry key. See The code font.
fontsize 11pt PDF base size; the allowed set depends on the target. See Base font size.
linestretch 1.0 Line-spacing multiplier (PDF); 1.15 looser, 2.0 double. See Typography.
justify-control auto auto (target default) or disabled (ragged-right).
indent-control auto auto (target default) or disabled (no first-line indent).

auto follows the target's convention — justified, first-line-indented body for book; block paragraphs for article/report.

Key Default Notes
colorlinks false Color link text instead of boxing it; gates the colors below.
linkcolor — Internal links and cross-references.
urlcolor — External URLs.
citecolor — Citations.
toccolor — Table-of-contents entries.

Each color is a quoted #RRGGBB hex value. See Typography.

Notes & citations

Key Default Notes
keystone-note-placement target default footnotes or endnotes (PDF).
bibliography — A .bib/CSL-JSON file (or list) in manuscript/; enables citations.
csl chicago-author-date A shipped style name or a .csl file in manuscript/.
link-citations true Hyperlink citations to the bibliography.

nocite is also supported for including uncited entries. See Notes & citations.

Running headers & footers (PDF)

Key Default Notes
header-text, footer-text — Center-slot running content.
header-text-recto / -verso — Per-parity overrides (two-sided targets).
footer-text-recto / -verso — Per-parity footer overrides.
page-number-position footer:outer <row>:<col> placement of the page number.
header-rule disabled enabled draws a rule under the header.
marks — Author-declared running-header mark channels.

Fully covered in Running headers & footers.

Page layout (PDF)

Key Default Notes
papersize letter letter, a4, a5, b5.
geometry margin=1in LaTeX geometry syntax for margins.
classoption — A list of document-class options (oneside, twoside, twocolumn, landscape).
draft disabled enabled (a "DRAFT" watermark) or custom watermark text.
draft-scale auto Watermark size multiplier; empty auto-scales.

classoption: twoside/oneside flips a target's recto/verso behavior without changing the document class — see Targets.

Code & output metadata

Key Default Notes
code-theme tango Syntax-highlighting theme. See Code blocks.
xmp-metadata auto auto embeds an XMP packet in the PDF; disabled uses the Info dict only.

EPUB

Key Default Notes
cover-image — Path to the cover image (EPUB only), e.g. assets/cover.jpg.

Reserved keys

documentclass, css, and header-includes are standard Pandoc keys, but Keystone's targets own them — they carry the build's core wiring. Setting one in pandoc.yaml stops the build with an error naming the key (see Overriding a reserved key). Choose the layout with target (see Targets).