Skip to content

System shortcut reference

Every system shortcut Keystone ships, grouped by purpose and listed alphabetically. This is the lookup reference — the Writing guides teach each one by task. Attributes are shown with their defaults; an attribute with no default takes effect only when you supply it.

Most shortcuts are block-level, written as a fenced div (::: name). A few also work inline as a bracketed span ([text]{.name}): font, sym, dropcap, container, slot, set, ifdef, ifndef, and the four format-only shortcuts (latex-only, epub-only, docx-only, odt-only). set, appendix and container — through a heading shortcut built on it — also take a heading (# Title {.name}). The rest are divs only, being blocks by nature: alignment, spacing and breaks act on whole paragraphs. The shortcuts that render from attributes alone (pagebreak, vspace, rule, source, optional-source) take no content.

If a construct does nothing, check the class name against this list first: a name that matches no shortcut or native style is flagged as unrecognized during the build (and fails a strict build).

Values

An attribute takes what its entry below says, and any other value is refused. One described only in words — a title, an attribution — takes any text.

A CSS length is a number and a unit every format renders — em, pt, cm, mm or in — or a bare 0. It runs to 16383.99pt, and an em to 329em, counted at the largest font size. CSS's rem and px aren't among them: a PDF can't render either.

Callouts

aside

A callout box with a colored left border and tinted background.

  • type — tip · warning · note · example (default: note)
  • title — heading text; defaults to the capitalized type; an empty string removes it
  • color — #rrggbb accent color, overriding the type's default
  • border — none removes the left border
::: {.aside type="warning" title="Before you build"}
Commit your work first.
:::

See Asides & callouts.

Composition primitives

These exist mainly as building blocks for your own shortcuts. You can use them directly, but most authors won't need to.

container

A wrapper with no visual output — EPUB/HTML keeps the element and its classes; LaTeX passes the content through. Useful purely for grouping or nesting, or as the class of a heading shortcut.

optional-source

An attribution line with an em-dash prefix, right-aligned, for templates: renders nothing when its text is absent, so a composed shortcut's attribution stays optional.

  • text — the attribution

rule

A conditional horizontal rule — a line when style="ruled", nothing otherwise.

  • style — ruled renders the line; plain or absent, nothing

slot

A content placeholder used inside a shortcut's template, so author content and the template's fixed elements can sit side by side. It renders as container does, as a div or a span.

source

An attribution line with an em-dash prefix, right-aligned.

  • text — the attribution, not blank (required)

Conditional content

Gate content by build symbol. Symbols come from two places: the build configurations you declare in project.conf, and the format symbols Keystone defines automatically for every build (latex for PDF, plus epub, docx, odt) — those four are what the *-only shortcuts wrap. They're build config, not document metadata; for the full picture see the Conditional content guide in Writing.

docx-only / epub-only / latex-only / odt-only

Keep content only in one output format. Each build defines a format symbol (pdf → latex, plus epub, docx, odt), so these are thin wrappers over ifdef.

  • symbol — fixed to the matching format; writing it stops the build. For another gate, use ifdef
::: latex-only
\begin{center}Raw LaTeX, PDF builds only.\end{center}
:::

ifdef / ifndef

Keep content only when a symbol is (ifdef) or is not (ifndef) defined.

  • symbol — one or more whitespace-separated symbols, OR-combined (required)
::: {.ifdef symbol="personal"}
A dedication only the private edition carries.
:::

Dialogue

dialog

Turn a bullet list into dialogue lines, each opening with an em-dash.

  • style — hanging indents wrapped lines under the speech; default, or omitted, for the tight (flush) wrap
::: dialog
- Who's there?
- Just the wind.
- At this hour?
:::

See the Dialogue guide in Writing.

Document structure

appendix

Switch the chapters from the marker on — or sections, on article targets — to appendix numbering (PDF only). A one-shot marker; the label localizes from lang.

numbering — enumerator: upper-alpha (default) · lower-alpha · upper-roman · lower-roman · arabic

::: appendix
:::

::: {.appendix numbering="upper-roman"}
:::

On a heading, it switches just before that heading:

# Sources {.appendix}

See Appendices.

Figures

aligned-figure

A figure with alignment control — the figure wrapped in align.

  • align — left · center · right · justified · normal (the surrounding alignment; default: center)
  • width — a CSS length or a whole percentage to 100
  • caption-width — full to widen the caption
  • identifier — a cross-reference id (also settable with #id)
  • space-after — trailing space below the figure: a named size (tiny…huge) or a CSS length; none (default) for no gap
::: {.aligned-figure align="left" width="40%" #fig-map}
![Map of the region.](assets/map.png)
:::

figure

Wrap a Markdown image in a styled figure. The caption comes from the image's alt text. width constrains both the image and its caption.

  • width — a CSS length or a whole percentage to 100 (e.g. 50%, 5cm)
  • caption-width — full lets the caption span the full text width instead of matching the image
::: {.figure width="60%"}
![A lighthouse at dusk.](assets/lighthouse.jpg)
:::

See Figures & images.

Layout & spacing

multicol

Lay content out in multiple columns.

  • cols — 2 to 4 (default: 2)
::: {.multicol cols="3"}
Content flowing across three columns.
:::

no-indent

Suppress first-line paragraph indentation within its scope — for dedications, poetry, or title pages.

::: no-indent
For my parents,\
who read to me.
:::

pagebreak

Force a page break. Empty div only.

::: pagebreak
:::

scene-break

A decorative break between scenes. An empty div renders a default * * * ornament; supply content to use your own.

::: scene-break
:::

vspace

Insert explicit vertical space. Empty div only.

  • size — a named size (tiny · small · medium · large · huge), a CSS length (e.g. 1.5em, 3cm), or none for no space (required)
::: {.vspace size="large"}
:::

See Breaks & spacing.

Quotations

epigraph

A chapter-opening quotation: narrowed italic text with optional attribution.

  • source — attribution text (rendered with an em-dash prefix)
  • font-style — a font style; normal for upright (default: italic)
  • font-family, font-size — a font family or size
::: {.epigraph source="John Keats"}
A thing of beauty is a joy forever.
:::

pullquote

A mid-chapter quotation: centered, large, italic, with optional rules.

  • align — left · center · right · justified · normal (the surrounding alignment; default: center)
  • style — plain or ruled (rules above and below; default: plain)
  • source — attribution text
  • font-size — a font size (default: large)
  • font-style — a font style; normal for upright (default: italic)
  • font-family — a font family
::: {.pullquote style="ruled" source="Ursula K. Le Guin"}
The only thing that makes life possible is permanent, intolerable uncertainty.
:::

quote

Wrap content in a narrowed block with left and right indents.

::: quote
A narrowed, indented passage.
:::

See Quotes & epigraphs.

Running-header marks

set

Set an author-declared running-header mark at a point in the flow. A span or div shows nothing in any format; the effect appears only in PDF running headers. The value persists until the next set for that mark.

  • mark — the declared mark channel (required; declare it under marks: in pandoc.yaml)
[John Keats]{.set mark="poem-author"}

On a heading, it sets the mark to the heading's own text, and the heading stays:

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

See Running headers & footers.

Text & fonts

align

Set the horizontal alignment of block content.

  • style — left · center · right · justified · normal (the surrounding alignment)
::: {.align style="center"}
Centered text.
:::

See Alignment & columns.

dropcap

Enlarge the opening letter of a passage. As a div, Keystone extracts the first character automatically; as a span ([T]{.dropcap}) you choose the letter.

  • lines — how many lines tall the drop cap is, 1 to 10 (default: 3)
  • font-family — a registry name for the drop-cap letter only
::: dropcap
Every story begins somewhere, and this one begins here.
:::

font

Apply a font family, size, and/or style. The three are independent and combine.

  • family — a font registry name (e.g. eb-garamond, libertine)
  • size — tiny · scriptsize · footnotesize · small · normalsize · large · Large · LARGE · huge · Huge
  • style — italic · bold · bold-italic · normal (upright, regular weight)
::: {.font family="eb-garamond" size="large"}
A passage in large EB Garamond.
:::

A [bold aside]{.font style="bold"} inline.

See Typography & fonts.

sym

Render a run in Latin Modern Math, the shipped font with comprehensive Unicode math coverage, for symbols a body font lacks (e.g. ≫, ⩽, ∀) that would otherwise drop silently. 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. It is font preset to the symbol face — override family or size as with font.

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

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

See Typography & fonts.