Skip to content

Mistakes Keystone can't catch

Most of Keystone's checks run on your document after Pandoc has read your Markdown into a document tree. A mistake that stops Pandoc from building an element in the first place leaves nothing for them to inspect. The lint reads your source before that and catches some of these; the ones below get past it too, and leak into your book. Knowing this boundary matters as much as knowing the checks.

Malformed fences

A fenced div needs three or more colons. Type two and it isn't a fence at all — Pandoc sees plain text, no element is created, and the line prints verbatim in your book:

:: vspace size="medium" ::

No warning, no error — the literal text :: vspace size="medium" :: appears on the page. Keystone never saw a vspace. The rule this breaks — three-or-more colons, flush left — is on Markup syntax.

Unclosed spans

The same applies to a bracketed span you forget to close. Pandoc treats the stray [ as ordinary text; no span is created, nothing is flagged:

Here is [an unclosed span with no closing bracket, so it stays literal.

The correct form — brackets closed, attributes attached with no gap — is on Markup syntax.

Dead cross-references

An internal link resolves only if a heading (or any element with an #id) actually carries the id it points at. Aim one at an id nothing has — most often because a heading's derived id isn't the one you typed — and Pandoc still builds a valid link. It just leads nowhere in the finished book. No warning, no error:

See [the recap](#recap).   ← no heading has the id `recap`

Both the remedy — pinning an explicit {#id} on the heading you link to — and the GitHub id mismatch that trips this most often live on Markup syntax.

The ones that are caught

The lint reports some structural slips at their line — an unclosed div, and a fence, heading, block quote or list on the line after paragraph text, among them. The mistakes above are silent.

What fills the gap

Because these slip through, a few habits do the checking Keystone can't:

  • Always close your fences and brackets — every ::: opener needs its closer; every [ needs its ].
  • Pin {#id} on headings you link to — so a cross-reference targets an id you chose, not one derived from the heading text.
  • Turn on strict mode before you publish — it turns the mistakes Keystone does catch as warnings into hard stops, so a clean strict build is a real signal.