verify-docs.py

Documentation-integrity checker: verifies that the topic and guide pages, their frontmatter, sidebars.ts and the links between pages agree with one another. Standard library only; it does not invoke Docusaurus.

When to use

  • After adding, renaming, moving or deleting a topic or guide page, or editing sidebars.ts.
  • As part of a full build: build-docs.py runs it in its Verify stage and fails the build on errors.
  • For links from Juneau source and Javadoc to topics, use check-topic-links.py. For the project modules in src/data/projects.ts, use check-doc-inventory.py.

Usage

python3 scripts/verify-docs.py
python3 scripts/verify-docs.py --strict --anchors
python3 scripts/verify-docs.py --only links,imports
python3 scripts/verify-docs.py --skip 13,15 --json

Options

OptionArgumentDefaultMeaning
--strictnoneoffWarnings also make the exit code non-zero.
--anchorsnoneoffEnable check 14 (anchor-target resolution).
--jsonnoneoffPrint machine-readable JSON instead of the text report.
--onlycomma-separated numbers or namesall checksRun only these checks.
--skipcomma-separated numbers or namesnoneSkip these checks.
--docs-dirdirectoryparent of scripts/Docs root to check.

What it does

Topic pages live in pages/topics/*.md. Each needs frontmatter with a title and a slug (an id is optional; the effective id is the id when present, else the file name without .md). File names look like NN(.NN)*.PascalName.md; landing pages (the target of a sidebar category link) carry a trailing .00. Sidebars reference pages as topics/<id>, and body links use /docs/topics/<slug>. It reads sidebars.ts as text (no Node), starting at mainSidebar: and looking through the numbered(...) and group(...) helper calls; any other call expression is a parse error (check 6).

Guide pages live in pages/guides/*.md, with the same file-name rules but no .00 landing suffix. Each sets id equal to its file stem (Docusaurus would otherwise strip the NN. prefix) and slug equal to the name part, and body links use /docs/guides/<slug>. The landing 00.Guides.md is the exception: its slug is /guides, so it is served at /docs/guides. Checks 1-9 and 12-15 look only at topics; guides have check 16.

The checks, in reporting order (errors unless marked warning):

#NameVerifies
1frontmattertitle and slug present and non-empty.
2slug-filenameThe slug equals the PascalCase name part of the file name.
3filename-formatThe file name matches ^\d\d(\.\d\d)*\.[A-Z][A-Za-z0-9]*\.md$.
4unique-idsSlugs and effective ids are unique.
5landing-00Category link targets end in .00 and leaf pages do not.
6danglingEvery sidebar topics/<id> resolves to a file.
7orphansEvery topic file is referenced in sidebars.ts, except ids listed in scripts/verify-docs-allowlist.txt.
8countsFile count versus distinct sidebar references.
9orderSidebar depth-first order equals directory order.
10(retired)Retired: sidebar labels carry no numbers (numbered() in sidebars.ts generates them from position), so there is nothing to compare with the file prefix. --only 10 and --only labels are rejected as unknown checks.
11links/docs/topics/<slug> and /docs/guides/<slug> links resolve (/docs/guides itself is the landing); bare relative links on topic and guide pages are errors (the site uses trailing slashes, so write /docs/topics/<slug> or /docs/guides/<slug>).
12imports@site/pages/topics/<file> imports resolve.
13javadoc/site/apidocs/... link count and format sanity (warning).
14anchors/docs/topics/<slug>#<fragment> heading targets exist; only with --anchors (warning).
15hygieneDuplicate titles, near-empty pages, stray files (warning).
16guidesOnly when pages/guides/ exists. Each guide has id, title and slug; the file name matches check 3‘s pattern; id equals the file stem; slug equals the name part (the landing’s is /guides); 00.Guides.md exists; mainSidebar has exactly one category, at the top level, whose link is guides/00.Guides; in it every guides/ doc resolves to a file, every topics/ ref resolves to a topic, every guide except the landing is listed exactly once, the guides are listed in file order, the refs come after the guides, and every numbered landing row that links /docs/topics/<slug> has a ref to that topic (so a sidebar regeneration cannot drop guides 8 and 9 unnoticed).
17lockfileOnly when package-lock.json exists. Every resolved URL starts with https://registry.npmjs.org/ and the rest is <name>/-/<file>.tgz or @scope/name/-/<file>.tgz (so .../npm/ws/-/ws-8.22.1.tgz fails) (a local npm mirror setting can otherwise leak into the lockfile).

Output and exit codes

A text report grouped by severity (or JSON with --json) on stdout, ending with counts. Nothing is written.

CodeMeaning
0No errors (and no warnings under --strict).
1At least one error, or a warning under --strict.
2pages/topics was not found, or --only/--skip named an unknown check.

Gotchas

  • Only topic and guide pages are checked, not release notes or the developer-info pages (check 11 reads links on every page).
  • Ordering and landing-page rules are strict by design; renaming a page usually means renumbering its siblings.
  • --only and --skip accept either the number or the name from the table.

See also

  • build-docs.py, check-topic-links.py, check-doc-inventory.py, normalize-headings.py