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 commented — a line per key, grouped, each group linking the page that owns it. What the project is called and how it builds is project.conf.

Where a key below names a default, it is the value pandoc.yaml ships. An empty key takes the engine's fallback instead, which for some keys is a different value; toc, numbersections and colorlinks reject an empty value outright. Many keys are explained in depth in their own guide; this page links out rather than repeating them.

Identity

title and author are required for every target.

Summary fields

Your target requires one of these (see Targets); Keystone fills the others in from it, abstract to description to subject, so setting the one your target asks for populates every slot:

Structure

See Manuscript & structure for headings and numbering.

Body text

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

Link colors (PDF)

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

Notes & citations

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

Running headers & footers (PDF)

Fully covered in Running headers & footers.

Page layout (PDF)

geometry is where LaTeX keeps four separate jobs: the size of the page, the margins around the text, the gutter a binding takes, and which way the page turns. auto settles the margins and, with them, orientation; it leaves the size to papersize and reserves nothing for the gutter. Options of your own replace auto — the sections below cover each job in turn, because which of them a value takes over is not all-or-nothing.

Page sizes

papersize names one of:

Every name works on every target. For a trim size with no name — most print-on-demand formats — give the dimensions to geometry and leave papersize empty:

papersize:
geometry: paperwidth=6in,paperheight=9in,margin=0.75in

geometry can also name a size itself — the a5paper spellings, and screen, a fixed 225×180mm page for reading on a display rather than printing. Those size the page as much as the dimensions above do.

A small trim wants a smaller base size with it: at 11pt an A6 page cannot reach a comfortable line length at any margin — see Base font size.

Margins

auto sizes the text block to the page. On a two-sided target it also splits the side margins unevenly, setting the inner margin — the one at the spine — narrower than the outer, following the convention that the two inner margins of an open spread meet and read as a single band.

Options of your own replace that with whatever they say:

geometry: inner=30mm, outer=20mm, top=25mm, bottom=25mm

classoption: twoside/oneside flips a target's recto/verso behavior — and with it which side is inner — without changing the document class. See Targets.

The gutter

A perfect-bound book curves into the spine, and part of the inner margin turns away from the reader with it — more of it the thicker the book. Text set to the convention above will sit in that curve. The extra inner margin that pulls the text clear is the gutter.

So a bound book wants its inner margin widened, the opposite of what the convention gives. Any options of your own replace auto rather than adding to it, and auto alongside them stops the build. Replacing it need not mean writing four margins, though: bindingoffset reserves the gutter and leaves the proportions alone:

geometry: bindingoffset=10mm

The size still comes from papersize: a geometry speaking only about margins does not replace it.

Print-on-demand platforms publish a minimum inner margin per page count — match theirs, either through that offset or by setting the margins directly:

geometry: inner=30mm, outer=20mm, top=25mm, bottom=25mm

The two combine when a platform specifies both:

geometry: inner=20mm, outer=20mm, bindingoffset=10mm

Orientation

Orientation follows whoever owns the page. Under auto that is Keystone, so classoption: landscape turns it:

papersize: a5
geometry: auto
classoption: [landscape]

Give geometry options of your own and the page becomes yours, orientation included — landscape goes among them, and a classoption: landscape alongside stops the build rather than being quietly dropped:

papersize: a5
geometry: inner=30mm, outer=20mm, landscape

The build stops because LaTeX honors a class option when the page is named and ignores it when the page is given in dimensions. Writing it in geometry holds either way, so that is where it goes once the page is yours.

Code & output metadata

EPUB

Reserved keys

Anything starting with keystone- belongs to the target that declares it, so no key you set carries that prefix. documentclass, css, and header-includes are standard Pandoc keys the targets own as well — all of them 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).