The most common broken link on a documentation site points at the same page.

An anchor is a fragment: the # portion of a URL. It resolves against an id or a heading slug on the destination page, and the slug is derived from the heading text.

So editing a heading changes its slug. Fixing a typo, switching to sentence case, adding a word for clarity, all produce a new id, and every existing link to the old one now lands at the top of the page or nowhere.

The same applies to reordering: anchors survive reordering only if the slug is unchanged, which is why generated documentation that rewrites headings on every pass loses its deep links repeatedly.

Given a document, a check can extract every heading, compute the slug each one produces, and list every internal fragment link it contains. Comparing the two lists gives you the dead ones.

Links of the form /page#section need both pages. A single-document check cannot resolve them, so it should report them as unresolved rather than as broken.

Resolving them needs a crawl of the site, which is a different job: fetch each page, extract ids, then check fragments against the extracted set.

That is worth doing after any content migration, and it is the check that catches the long tail of anchors linked from support documentation and old campaigns.

Two habits cover most of the risk. Lock the id explicitly where a heading is likely to be linked, and leave a redirect or a stub where a section is removed.

In markdown that means writing the anchor as an explicit attribute rather than relying on the generated slug, at least for the sections you know are cited: installation, configuration, troubleshooting, pricing.

The other habit is to treat heading text as an interface. Changing it is a change to a contract, and it deserves the same review as a changed API parameter.

Rewrites destroy anchors in bulk, and the damage is invisible on the page: everything renders, and the links that matter are in other people's bookmarks and support threads.

So crawl the site immediately after publishing, compare the fragment set against the previous version, and either restore the ids or add redirects for the ones that cannot be.

Record the mapping. A small table of old fragment to new fragment is the artefact that makes the next rewrite survivable.

It does not tell you whether the section an anchor points at is the section the reader needed. A link can resolve perfectly and still send somebody to the wrong place.

It also does not check external destinations, which is link rot rather than anchors, and it does not see fragments that are generated by client-side JavaScript at runtime.

Those need a crawl and a renderer respectively, which is why anchors and link integrity are usually separate audit passes.