Skip to content

Lint findings

Before Pandoc reads your book, Keystone lints it: the chapters in publish.txt, read together in that order as Pandoc reads them, and the bodies in your shortcuts.yaml. The linter is pandoc-lint, and each finding names its file, line and column.

What it looks like

# Chapter

Opening text
::: aside
Body.
:::

Publishing target: 'book' | format: pdf
manuscript/chapter.md:4:1: ERROR: div fence is read as paragraph text
  │ 4 | ::: aside
  │   | ^^^^^^^^^
  A paragraph runs on to the next blank line: a div fence on the line after its
  text is part of it.
  Put a blank line before it; if it is meant as text, escape its first character
  with a backslash.
  ✗ Linting your manuscript      0.0s
ERROR: publishing failed during the lint
  See https://keystone.knight-owl.dev/errors/lint/

manuscript/chapter.md:4:1 is a location your editor opens.

What it means

Each finding is an ERROR or a WARN. An error stops the build, strict or not; a warning stops only a strict build. pandoc-lint's rules lists each one with its severity.

Markup Pandoc would misread

A div fence, a ~~~ code fence, a heading, a block quote or a list on the line after paragraph text becomes part of the paragraph, without a word from Pandoc: Ingredients: followed by - flour prints as one line. The lint reports it as an ERROR.

Put a blank line before the block

The blank line ends the paragraph above it. A line meant as text takes a backslash before its first character.

Metadata in a chapter

A YAML metadata block or a % title block in a chapter is an ERROR. A book's metadata has one home.

Move its fields into pandoc.yaml

They belong in pandoc.yaml. An imported document's arrive in a file of their own, ready to merge.

Warnings

Some warnings are misreads Pandoc passes in silence, so the lint's is the only report: a reference link or note nothing defines prints as bracketed text, and a closing fence whose length differs from its opener's in a nested div closes the nearest one. Others are Pandoc's own — an unclosed div, an identifier used twice — and a lenient build shows them again in Pandoc's words. Pandoc's line can differ from the lint's when a book has several chapters; the lint's is the one in your file.

Clear them before you publish

A strict build stops on any warning, so a clean one confirms there are none left.

Shortcut bodies

A shortcut's body is linted as a document of its own; its findings land at their line in shortcuts.yaml, or at the start of a folded or quoted body.

Turning the lint off

For a finding that is wrong, or a lint that cannot run, set KEYSTONE_LINT=false in project.conf to skip the lint, and report the finding to pandoc-lint.