Configuring Extensions

All markdown extensions are enabled by default. You can disable individual extensions in your config.yaml under the markdown: section. For example, to disable smart punctuation and subscript:

markdown:
  smart_punctuation: false
  subscript: false

The full list of toggleable extensions and their defaults is in the Configuration Reference.

Smart Punctuation

When enabled (default), straight quotes and dashes are converted to typographic equivalents:

Input	Output
`"quotes"`	“quotes” (curly quotes)
`'single'`	‘single’ (curly single quotes)
`--`	en dash
`---`	em dash
`...`	ellipsis

Quote characters are then remapped to the page locale’s typographic conventions: German and Czech open at the bottom („hello“), French uses guillemets («hello»), Japanese uses corner brackets (「hello」), and so on. The locale is taken from the page’s frontmatter (locale: fr), then markdown.locale in config.yaml, then the page’s language. See Markdown Extensions: Smart Punctuation for the full mapping table.

Definition Lists

Term
  : Definition of the term.

Another term
  : Its definition.
  : A second definition.

Renders as <dl>/<dt>/<dd> HTML elements.

Superscript and Subscript

Water is H~2~O and energy is E=mc^2^.

~text~ renders as subscript (<sub>)
^text^ renders as superscript (<sup>)
~~text~~ still renders as strikethrough (<del>)

Subscript never contains spaces. ~2~ and ~4~ are subscript; a run of tildes spanning whitespace is left exactly as you typed it. This is what lets you use ~ for “approximately” in ordinary prose without escaping it:

The binary is (~50 KB); the engine bundles to (~12 MB).

renders literally as “(~50 KB)” and “(~12 MB)”, even though two tildes share one paragraph. Without that rule they would pair into a single subscript span swallowing the text between them. If you want a subscript containing a space, write the markup directly: <sub>like this</sub>.

Subscript can be turned off entirely with subscript: false, in which case ~text~ is left alone in every position.

Admonitions (Callouts)

GFM blockquote alerts render as styled callout boxes:

> [!NOTE]
> Useful background information.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

All five kinds are supported: Note, Tip, Important, Warning, and Caution. Each renders with a distinct border color and title. Admonitions can be disabled with markdown.admonitions: false in config.yaml.

Math Expressions

Inline and display math using LaTeX syntax, rendered client-side by KaTeX:

Inline: The equation $E = mc^2$ changed physics.

Display (block-level):

$$\int_0^1 f(x)\,dx = F(1) - F(0)$$

Inline math uses single dollar signs ( $...$ ) and renders within the text flow. Display math uses double dollar signs ($$...$$) and renders as a centered block.

Rendered live, the same two examples look like this: the equation $E = mc^2$ changed physics, and as a display block:

\int_0^1 f(x)\,dx = F(1) - F(0)

The default theme automatically loads KaTeX from CDN only on pages that contain math expressions (via the page.has_math template flag). Math can be disabled with markdown.math: false in config.yaml.