Hyperbook Documentation

Lint

hyperbook lint finds problems in your pages without building the book. It runs every page through the same pipeline a build uses, but writes nothing.

hyperbook lint                  # every page of the book or library
hyperbook lint book/intro.md    # only these pages or folders
hyperbook lint --json           # machine-readable, for scripts and AI agents

It reports:

Rule What it means
unknown-directive An element name Hyperbook does not know, like :::alret. Its content is dropped from the page. Lint suggests the closest name.
unclosed-directive A ::: block without its closing :::. Everything after it ends up inside the block.
malformed-directive A line that was meant to be an element but could not be read, e.g. :: youtube with a space, or an unclosed quote in {…}. It shows up as plain text.
stray-directive-fence A ::: that closes nothing. It shows up as plain text.
unknown-attribute An attribute the element does not read, like titel= on :::collapsible. It has no effect. Lint suggests the closest one.
invalid-attribute-value A value the element does not know, like mode="edit" on :::p5 (it takes preview or editor).
missing-file A file an element points at (src, poster, …) that is neither in public/ nor next to the page.
broken-link A link or image pointing at a page or file that does not exist.
duplicate-permaid Two pages with the same permaid.
unknown-config-key An option in hyperbook.json that Hyperbook does not know.
not-a-page A path given to lint is not a page of the book.

The elements also report their own problems, such as a src attribute that is missing or an element written with the wrong number of colons (wrong-directive-form). These are the same messages hyperbook build prints, and every one of them has a rule.

Lint exits with code 1 if it finds an error or a warning. With --strict, infos fail too.

For AI agents

Add something like this to the AGENTS.md or CLAUDE.md of your book, so an agent checks its own work:

After editing pages, run `npx hyperbook lint --json <changed files>` and fix
every finding before you finish. Each finding has a file, line, rule and message.

The JSON looks like this:

{
  "ok": false,
  "pages": 1,
  "errors": 0,
  "warnings": 1,
  "infos": 0,
  "findings": [
    {
      "file": "book/index.md",
      "line": 5,
      "column": 1,
      "severity": "warning",
      "rule": "unknown-directive",
      "message": "Unknown directive \":::alret\". It is shown as plain text and its content is dropped. Did you mean \":::alert\"?"
    }
  ]
}
Lint

Create Shareable URL

Select Sections

✎ GitHub© Copyright 2026 by OpenPatch