Link checking
The site is link-checked with two tools:
- htmltest — the original checker and current default, run by
check:links. It is installed automatically on first run, if necessary, so no setup is needed. It also backs the scripts and workflows related to the refcache. - Lychee — a faster alternative that contributors can test drive.
⚠️ You must install Lychee locally first.
Check links
To check links locally (using htmltest), run:
npm run check:links
Or to try Lychee run the following after installing it:
npm run _lychee -- check:links
Want to use Lychee instead? Once you’ve installed it, either prefix a one-off run:
npm run _lychee -- check:links
or set the following environment variable to have all npm scripts that rely on
it (directly or indirectly, such as check:links, check, etc.) use Lychee:
export LINK_CHECKER=lychee
Common commands
| Command | Checking scope | Checker |
|---|---|---|
check:links | Whole site | LINK_CHECKER (default htmltest) |
check:links:htmltest | Whole site | htmltest |
check:links:lychee | Whole site | Lychee |
check:links:diff | Changed files only | Lychee |
The check:links and check:links:* scripts run over a build of BUILD_KIND.
For details, see Build kinds: full and lean
Refcache
The site has an external-link cache (refcache) under version control. It is
created and updated by htmltest. Lychee is not currently setup to refresh the
refcache. To refresh the refcache, run either fix:refcache or check links with
htmltest.
Refcache refresh and housekeeping workflows
The following workflows are scheduled daily and run a link checking command:
| Workflow | Checker | Build |
|---|---|---|
Refcache refresh (fix:refcache) | htmltest | full |
Housekeeping (fix-and-test:all) | htmltest | full |
Refcache refresh prunes the refcache and runs check:links:htmltest, which
refreshes the refcache for the pruned entries, if they are still used in the
docs.
The housekeeping workflow runs fix-and-test:all, which calls
fix:refcache and deliberately skips check:links so links are checked exactly
once (via htmltest, refreshing the refcache).
In CI
The check-links.yml workflow builds the site once (lean) and shares that
artifact across the htmltest shards and the Lychee check, so local runs and CI
check the same build.