Skip to content

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. libertine (Linux Libertine) is the default:

fontfamily: eb-garamond
fontsize: 11pt          # 10pt, 11pt, or 12pt

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/italic support, except the three DejaVu families, which are system fonts (PDF + CSS fallback in EPUB, not embedded as files).

Key Font Category
libertine Linux Libertine Serif
biolinum Linux Biolinum Sans
eb-garamond EB Garamond Serif
latin-modern Latin Modern Roman Serif
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

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 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 .otf, 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 (.otf) and live flat in fonts/ (no subdirectories).

Decorative ornaments

Three single-variant ornamental faces — fourier-ornaments, imfell-flowers-1, and imfell-flowers-2 — provide fleurons and floral printer's ornaments, accessed through the font shortcut like any other family. They render in PDF and EPUB only; glyph access differs per font. These pair naturally with a scene-break or a custom shortcut.