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. |
numbersections |
true |
Number headings; exempt one with {.unnumbered}. |
See Manuscript & structure for headings and numbering.
Body text
| Key | Default | Notes |
|---|---|---|
fontfamily |
libertine |
Document font; any registry key. See Typography. |
fontsize |
11pt |
10pt, 11pt, or 12pt (PDF). |
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.
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 folio. |
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. |