Skip to content

The shortcut system

Shortcuts are how you style content in Keystone. When you write a fenced div or a bracketed span with a class name, you're invoking a shortcut:

::: dialog
- Who's there?
- Just the wind.
:::

A word in [small caps]{.font style="bold"} mid-sentence.

dialog and font are shortcuts. Keystone ships a complete set of them — the system shortcuts — and you can define your own on top.

Two layers

  • System shortcuts ship with Keystone and cover every built-in styling capability: font, align, figure, aside, dialog, quote, and the rest. They're always available — you don't declare them. The reference lists them all.
  • User shortcuts are yours, defined in shortcuts.yaml. They build on the system shortcuts to create project-specific vocabulary — define garamond once instead of repeating font family="eb-garamond" everywhere. See Writing your own shortcuts.

How you use them

Shortcuts are written like any Pandoc class. Most are block-level:

  • As a fenced div — ::: name … ::: — for block content (paragraphs, lists, images).

Some also work inline, as a bracketed span — [text]{.name} — for runs inside a paragraph. Inline support is per-shortcut (font, dropcap, set, the conditional shortcuts, and a few others); the reference notes which.

Most shortcuts accept attributes that tune their behavior, written in the Pandoc attribute syntax:

::: {.font family="eb-garamond" size="large"}
A passage in large EB Garamond.
:::

Each shortcut's reference entry lists the attributes it accepts and their defaults. An attribute the shortcut doesn't recognize produces a build warning — that's typo detection, not a hard failure.

Build on the stable layer

The system shortcuts are a public promise: once a shortcut or one of its attributes ships, it's never removed or renamed. Your markup keeps working across Keystone versions.

Behind each system shortcut is an internal handler whose name starts with the reserved ks- prefix (font → ks-font). Those handlers are private and carry no such promise — they can change or disappear between releases. So write the system shortcut, never the ks- handler, and build your own shortcuts on the system names too. The system layer absorbs internal changes so your manuscript doesn't have to.

Reserved prefix

A shortcut you define may not start with ks- — that prefix is reserved for the internal handlers.