lychee anchor / fragment "not found" in CI

lychee can validate #fragment anchors against the heading ids on the target page. When the fragment does not match any generated id (usually a renamed or mis-slugged heading), it reports the anchor as an error.

What this error means

lychee reports a link with a fragment as failing, noting the anchor was not found on the page, for example "#instalation | Anchor not found".

lychee

[docs/guide.md]:
  [ERROR] ./setup.md#instalation | Anchor "instalation" not found

Errors: 1

Common causes

The fragment does not match the heading slug

A typo or a renamed heading means the #anchor no longer maps to a generated id on the target page.

Slug generation differs from the checker

Some renderers slugify headings differently than lychee expects, so a valid-looking anchor still fails.

How to fix it

Correct the fragment to the real slug

Match the anchor to the slugified heading text (lowercase, spaces to hyphens).

guide.md

<!-- heading: ## Installation  ->  slug: installation -->
See [setup](./setup.md#installation)

Disable fragment checking if slugs differ

If your renderer slugifies differently, turn off fragment validation so only the page URL is checked.

lychee.toml

# lychee.toml
include_fragments = false

How to prevent it

Keep anchors in sync when you rename headings.
Match the slug rules your docs renderer uses.
Disable fragment checks only when slug generation genuinely differs.