Running headers & footers

Running headers and footers are the lines of context that repeat across a book's pages — the title, the current chapter, the page number. Keystone composes them from pandoc.yaml.

Opening pages carry neither the running header nor the body footer — the heading is the only landmark there, and running content resumes on the next page. The one line they do carry is covered under Opening pages.

Header and footer text

Set free-form inline content for the header, the footer, or both:

header-text: "The Lighthouse"
footer-text: "© 2026 Jane Doe"

This puts the text in the center slot. Set any key to disabled to suppress it.

On a one-sided document the page number falls back to the center of the foot, so footer-text collides with it — see Page numbers.

Recto and verso

Two-sided books (book / scrbook) can carry different content on right-hand (recto) and left-hand (verso) pages — the classic layout has the book title on the verso and the chapter title on the recto:

header-text-recto: "{chapter}"
header-text-verso: "{title}"

Each parity key falls back to the un-suffixed header-text (or footer-text) when blank. On single-sided targets every page is treated as recto, so use the un-suffixed key there. Whether a target is two-sided is set by the target — see Targets.

Placeholders

Embed values with {name} tokens. Some resolve once at build time (static), others update as the document paginates (dynamic):

footer-text: "Chapter {chapter} — {page}"

To print a literal brace, double it ({{, }}). An unrecognized name emits a build warning and passes through as literal text — loud about the typo without breaking the build.

Substitution happens inside surrounding inline markup, so you can style a placeholder:

header-text: "**{chapter}**"                         # bold
header-text: "[{title}]{.smallcaps}"                 # small caps
header-text: "[{author}]{.font family=eb-garamond}"  # a different font

Page numbers

page-number-position places the folio, in the form <row>:<col>:

• row — header, footer, or header-and-footer
• col — left, center, right, or the parity-aware outer / inner

outer is right on recto and left on verso (the outside edge, where a thumbing finger lands); inner is the mirror. On single-sided targets, outer resolves to right.

The default follows the shape of the document. Two-sided documents — book and scrbook, or any target you flip with classoption: twoside — put the folio on the outside edge, footer:outer. One-sided documents center it, footer:center, as the one-sided classes do themselves.

page-number-position: footer:outer

If the page number lands on a row's center slot and that row also has text, the page number wins and the text is suppressed with a build warning. On a one-sided document the folio falls back there, so footer-text collides with it unless you move one: footer:outer puts the folio at the right edge and keeps both.

This governs body pages. Opening pages carry their own folio, which follows this column only if you ask it to — see Which column it sits in.

Opening pages

An opening page is a chapter's first page and the first page of the table of contents. Unnumbered chapters count, so a preface, a dedication, or an appendix is one too. Each carries a single line at the foot — the page number, centered, which in that position is called a drop folio.

footer-text-opening: "{page}"    # what an empty key renders

footer-text-opening takes the same content as any other running key, so the folio can be framed or styled:

footer-text-opening: "— {page} —"

Set it to disabled for a fully bare opening — every opening page, since the key is document-wide.

Opening pages arrive with chapters, so a manuscript on article or scrartcl normally has none.

Which column it sits in

footer-text-opening-column takes center or auto. Empty, as it ships, centers: a drop folio is centered by convention, whatever the body pages do. auto puts the line in whichever column the body folio occupies. No other value is accepted — the column names belong to page-number-position, and auto is how you follow them here.

page-number-position: header:outer
footer-text-opening-column: auto

That pair holds the folio to the outside edge throughout. It still drops from the head to the foot on an opening page — there is no running header to hold it — but it no longer crosses to the middle.

auto takes the column and ignores the row, so this line stays at the foot however you place the body folio. center and auto settle alike wherever the body folio is already centered — which is the fallback on a one-sided document.

There are no recto and verso variants: one line serves both parities, and it mirrors across a spread only under outer or inner.

Leaving the column centered while the body folio sits in the header puts folios in two places on an opening page. That is the drop folio working as intended; auto brings the two together, and footer-text-opening: disabled removes the second.

The header rule

By default there's no rule under the running header. Add a thin one on body pages with:

header-rule: enabled    # default: disabled

It follows the running header, so it never appears on an opening page.

The canonical book pattern

Trade and academic books converge on this:

header-text-recto: "{chapter}"
header-text-verso: "{title}"
page-number-position: footer:outer

The reader sees the book title on the left of every spread, the chapter on the right, and the folio on the outside edge. On a two-sided document footer:outer is already the fallback, so that line can be left empty.

Author-declared marks

The six built-in placeholders track metadata and headings. For running content that no heading tracks — a poetry anthology naming the current poem on each spread — declare your own mark channel in pandoc.yaml:

marks:
  - poem-author
  - poem-title

header-text-recto: "[{poem-author} — {poem-title}]{.smallcaps}"

Set a declared mark from the manuscript with the set shortcut. A span or div set shows nothing in any format, and the mark holds its value until the next set for that mark (empty content clears it):

[John Keats]{.set mark="poem-author"}

## Ode on a Grecian Urn {.unnumbered .set mark="poem-title"}

On a heading, set takes the heading's own text as the value, so the title is written once.

A mark name takes letters, digits, hyphen and underscore, starting with a letter, and may not reuse a built-in placeholder name.

{poem-author} then resolves in headers exactly like a built-in dynamic placeholder, per page. Declaring the mark is also what makes it typo-safe: an undeclared {name} warns and passes through, while a set naming an undeclared mark is a hard error.

For content you set repeatedly, wrap set in a shortcut so you set marks by meaning rather than repeating mark="…" — see Writing your own shortcuts.