Typography & fonts

Keystone ships a curated set of professional fonts and embeds them in your PDF and EPUB automatically. You pick a document font once, and override it locally wherever a passage needs a different face, size, or style.

The document font

Set fontfamily in pandoc.yaml to a registry key — one of the built-in fonts or a font you register yourself:

fontfamily: eb-garamond
fontsize: 11pt

Leaving fontfamily unset uses Keystone's default, latin-modern; an unrecognized value prints a warning and falls back to it — under strict mode it fails the build.

fontsize sets the base size; the sizes each target allows are listed under Base font size.

When a serif has a matched sans companion (Libertine pairs with Biolinum), it is selected automatically for sans contexts.

Built-in fonts

All of these embed in PDF and EPUB with full bold and italic support, with two exceptions. noto-mono has bold but no italic cut, so italic falls back to the upright regular in PDF and a synthesized slant in EPUB. latin-modern-math and the ornament faces are regular-only; see Math symbols and Decorative ornaments.

Key	Font	Category
`libertine`	Linux Libertine	Serif
`biolinum`	Linux Biolinum	Sans
`eb-garamond`	EB Garamond	Serif
`latin-modern`	Latin Modern Roman	Serif
`latin-modern-math`	Latin Modern Math	Math
`latin-modern-mono`	Latin Modern Mono	Mono
`tex-gyre-bonum`	TeX Gyre Bonum (Bookman)	Serif
`tex-gyre-pagella`	TeX Gyre Pagella (Palatino)	Serif
`tex-gyre-schola`	TeX Gyre Schola (Century Schoolbook)	Serif
`tex-gyre-termes`	TeX Gyre Termes (Times)	Serif
`tex-gyre-adventor`	TeX Gyre Adventor (Avant Garde)	Sans
`tex-gyre-heros`	TeX Gyre Heros (Helvetica)	Sans
`tex-gyre-cursor`	TeX Gyre Cursor (Courier)	Mono
`dejavu-serif`	DejaVu Serif	Serif
`dejavu-sans`	DejaVu Sans	Sans
`dejavu-mono`	DejaVu Sans Mono	Mono
`noto-mono`	Noto Sans Mono	Mono
`source-code-pro`	Source Code Pro	Mono
`fourier-ornaments`	Fourier Ornaments	Ornament
`imfell-flowers-1`	IM Fell Flowers 1	Ornament
`imfell-flowers-2`	IM Fell Flowers 2	Ornament

The code font

Set monofont in pandoc.yaml to a registry key to choose the face for code blocks and inline code, independent of the body fontfamily. It applies to PDF and EPUB; DOCX and ODT take their code font from the reference document.

monofont: dejavu-mono

Leaving monofont unset uses Keystone's default, latin-modern-mono; an unrecognized value prints a warning and falls back to it — under strict mode it fails the build.

Reach for this when the default code font lacks glyphs your listings need: Latin Modern Mono drops symbols such as ≥, ⊇, and ⇄, and a local font override cannot reach inside a code block. Setting monofont to a wider-coverage face fixes it document-wide: dejavu-mono covers those symbols — the widest coverage of the built-in mono faces. For code-heavy books, noto-mono and source-code-pro are contemporary faces suited to technical listings. Any registry key is accepted; the mono-category faces (latin-modern-mono, dejavu-mono, tex-gyre-cursor, noto-mono, source-code-pro) are the natural choices.

Line spacing

Set linestretch in pandoc.yaml to loosen or tighten the leading of body text — a multiplier where 1.0 is single-spaced. Around 1.05–1.15 reads comfortably in a book; 1.5 or 2.0 opens it up for review drafts.

linestretch: 1.15

This applies to PDF only. EPUB leaves line spacing to the reading system — reflowable readers hand that control to the reader, so a publisher-forced value is unreliable: some ignore it, others let it override the reader's own setting. DOCX and ODT do not carry it either. A non-positive or non-numeric value fails the build with a clear error.

Link colors

By default, links print as colored boxes. Set colorlinks: true to color the link text instead — the usual choice for a book — and pick a color per link type:

colorlinks: true
linkcolor: "#1A5FB4"    # internal links and cross-references
urlcolor: "#1A5FB4"     # external URLs
citecolor: "#7A3E9D"    # citations
toccolor: "#000000"     # table-of-contents entries

Each color is a #RRGGBB hex value — the form your OS color picker gives you. Quote it: a bare # starts a YAML comment. colorlinks gates the four colors; they do nothing while it is false.

This applies to PDF only.

Local overrides with `font`

The font shortcut changes the face, size, and/or style of a passage — as a block or inline. The three attributes are independent and combine freely.

::: {.font family="dejavu-sans" size="small"}
A note set in small DejaVu Sans.
:::

A run of [bold italic]{.font style="bold-italic"} in the middle of a sentence.

family — any registry key (built-in or custom)
style — italic, bold, or bold-italic
size — tiny, scriptsize, footnotesize, small, normalsize, large, Large, LARGE, huge, Huge

If you reach for the same override repeatedly, name it once as a shortcut:

garamond:
  class: font
  interface:
    family:
      bind: class.family
      default: eb-garamond
    size:
      bind: class.size
    style:
      bind: class.style

::: garamond
This paragraph renders in EB Garamond.
:::

See Writing your own shortcuts.

Drop caps

The dropcap shortcut enlarges the opening letter of a passage. As a div, Keystone extracts the first character; as a span, you choose the letter — use the span form when the opening isn't plain text (quotation marks, emphasis):

::: dropcap
Every story begins somewhere, and this one begins on a cold morning by the sea.
:::

["T]{.dropcap}he best way to predict the future is to invent it."

lines — how many lines tall (default 3)
font-family — a decorative face for the letter alone (PDF and EPUB only; DOCX/ODT ignore it)

A drop cap needs a paragraph long enough to wrap beside it — a three-line cap wants three or four lines of text. For short openings, use lines="2".

Custom fonts

To use a typeface beyond the built-in set, drop its .otf or .ttf files into fonts/ and register them in fonts/fonts-registry.yaml. Registered fonts work everywhere built-in fonts do — as the document font, in font overrides, and in shortcuts.

my-serif:
  main:
    file: MySerif-Regular.otf
    bold: MySerif-Bold.otf
    italic: MySerif-Italic.otf
    bold_italic: MySerif-BoldItalic.otf
  css: '"My Serif", "Georgia", serif'

Required: main.file (the regular weight) and css (a font-family stack whose first quoted name is the embedded EPUB family, the rest fallbacks).
Optional: bold, italic, bold_italic variant files, and sans (a companion sans registry key selected automatically when this is the document font).

Then reference the key like any built-in:

fontfamily: my-serif

Keystone validates the registry at build time — a missing font file, a key that collides with a built-in, or a missing required field is reported as a WARN in the build output and the entry is skipped. Font files must be OpenType or TrueType (.otf/.ttf) and live flat in fonts/ (no subdirectories).

Math symbols

Many mathematical and technical symbols — ≫ (much greater-than), ⩽, ∀, ℵ — are missing from body fonts, and drop silently when the font lacks them. The sym shortcut renders a run in Latin Modern Math, a shipped font with comprehensive Unicode math coverage, so the glyph appears without switching your document font:

The growth is [≫]{.sym} linear.

::: sym
∀x ∃y : x ⩽ y
:::

The font is embedded in PDF and EPUB, so the glyph renders from it there. DOCX and ODT have no fallback for this face, so the character passes through in the document font instead — coverage there depends on that font. You can also select the face directly as a family ([≫]{.font family="latin-modern-math"}); sym is the shorthand.

Decorative ornaments

Three single-variant ornamental faces — fourier-ornaments, imfell-flowers-1, and imfell-flowers-2 — provide fleurons, manicules, and floral printer's ornaments for fiction, accessed through the font shortcut like any other family (PDF and EPUB only). See Ornamental fonts for the glyph reference and scene-break recipes.