Check a corpus #

View this page as Markdown

Prompt:

Check the docs for broken links and bad front matter before we publish, and fix whatever it finds.

Also works: "Run the docs check in CI." "Why did the docs build fail?"

What your tool does #

• Runs tzdocs check --source docs, adding --include-hidden where the build includes hidden pages.
• Reads each finding line: the source file, the finding, and, for a code block, the line and the fence.
• Corrects the source file each line points to, without touching the generated output.
• Runs the check again until it prints its success line, then reviews the content and the rendered pages, which the check does not cover.
• When asked, adds the same command to the test suite, a pre-commit hook, or the deploy pipeline, ahead of the build.
• Asks nothing: the check writes nothing, and the corrections are edits to your source files.

Before your AI starts #

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

• The tool installed and the corpus's source folder (Getting started).
• Whether the build passes --include-hidden, so that the check covers the same pages.

Steps #

1. Run the check #

This command checks the folder docs.

tzdocs check --source docs

The check reads the Markdown source files and writes nothing. It prints each finding on its own line and exits with code 1 when there is any. For a corpus with no finding, it prints this line and exits with code 0.

check: clean — source metadata, routes, Markdown links, heading targets, and code fences passed the supported checks

Use only --source and, where needed, --include-hidden with check. The check ignores the values of build options and extra positional arguments. A build option without its value, or given twice, is still a usage error.

2. Read the lines #

Each line gives the source file and what is wrong. There are two kinds of line:

• A refusal stops the build before it writes anything, for example two files resolve to one slug /guides — guides/index.md and guides.md.
• An advisory finding lets the build proceed, for example broken internal link in index.md — install.md#setup matches no heading anchor on install.md.

A code-block finding also gives the fence's line and quotes its info string, so you can find the fence. Code fences says which line it gives and how it quotes. Refusals and findings lists every line the check can print, with its cause and its remedy.

3. Correct the sources #

Edit the source files the lines point to. The tool never rewrites a source. Page source gives the slug and front-matter rules that a refusal reports as broken, and Highlight a code block gives the fence line.

4. Run the check again #

Exit code 0 means the checks listed in step 5 passed. It says nothing about accuracy, command coverage, readability, or accessibility, so review the content and the rendered pages after it.

5. Put the check in a pipeline #

Run the same command in a test suite, a pre-commit hook, or a deploy pipeline before the build, so that a corpus with a finding never reaches a published site. The check covers:

• source metadata and routes;
• internal Markdown links to pages and redirects, inline and reference links alike, with their titles, in lists, block quotes, and tables;
• images and links to files beside the pages;
• heading anchors;
• code-fence metadata, including a title or a line set on a mermaid fence;
• callout markers, including a bracketed word that is not one of the five.

It skips link-like text inside code. It does not fetch external URLs, and it does not read images, links, or ids written in raw HTML.

The build, not the check, validates the output folder, the shell's markers, and whether the shell, opening, and stylesheet files exist. The build can also fail during generation or publication. A link to a missing page or a reference to a missing file stops the build as well. A missing heading, a bad fence, an unknown callout marker, or a declared section that names no top-level section does not stop the build. A pipeline that must stop on one runs the check first.

Expected result #

The check prints its success line and exits with code 0, and the build that follows prints its success line and exits with code 0. In a pipeline, a finding stops the run before the build.

Refusals #

The check itself rejects only a wrong command line. Every finding it prints is listed on Refusals and findings with its remedy.

Related #

• Refusals and findings lists every message with its cause and remedy.
• Page source gives the slug, front-matter, and link rules.
• Highlight a code block gives the fence line.