check-anchors duplicates mkdocs 1.6 validation.links.anchors on both consuming repos

[mairas]

check_anchors.py's module docstring says mkdocs build --strict "does not
validate anchors at all". That was true before mkdocs 1.6. It is not true now,
and both consuming repos are on mkdocs 1.6.1.

Setting

validation:
  links:
    anchors: warn

makes mkdocs build --strict fail on a broken fragment. Measured:

• On halos-org/docs, adding [Broken](index.md#no-such-heading-here) to
  docs/index.md produces exactly one warning and aborts the strict build. No
  other warning appears, so the existing content is clean under it, and
  print_page/ needs no exclusion — mkdocs validates source markdown, not
  generated output.
• On a two-page, one-locale probe with mkdocs-static-i18n, a fragment in
  docs/fi/second.md pointing at a heading absent from docs/fi/index.md is
  caught the same way. The cross-locale case that motivated check-anchors is
  covered.

The remaining unique coverage of check-anchors is links mkdocs does not parse
from source: root-absolute markdown links, and raw HTML <a href>. Counted
across both repos:

	halos-org/docs	hatlabs/halpi2
markdown links carrying a fragment	20	530
of those, root-absolute	0	0
raw HTML anchor links	0	0

So today check-anchors catches nothing in either repo that the config line
would not, while costing a dependency and a --exclude 'print_page/*' argument
that exists only because it reads generated output.

It is not strictly redundant — it checks the built site, so it would catch a
theme or plugin emitting a dead fragment, and root-absolute links if either repo
ever writes one. But the docstring's justification is stale and the value is
much smaller than it claims.

Decide one of:

1. Keep it, correct the docstring, and recommend validation.links.anchors in
   the README as the cheap first line of defence.
2. Keep it only for the built-site cases mkdocs cannot see, and document that
   narrower purpose.
3. Drop it, and have consuming repos set the config line instead.

[mairas]

An independent reviewer of halos-org/docs#38
produced the counter-evidence this issue was missing, and I reproduced it. The
conclusion above needs narrowing.

check-anchors does catch classes mkdocs' own validation does not. Measured on
halos-org/docs with validation: links: anchors: warn set, adding two links to
docs/index.md that point at headings which do not exist:

<a href="user-guide/dashboard/#raw-html-no-such-anchor">raw</a>

[abs](/user-guide/dashboard/#abs-no-such-anchor)

mkdocs build --strict exits 0. The absolute link draws only an INFO
("it was left as is"), and the raw HTML draws nothing at all — mkdocs parses
markdown links from source, so neither is a link as far as it is concerned.
check-anchors site --exclude 'print_page/*' reports both and exits 1.

So the two are complementary, not redundant:

	mkdocs validation.links.anchors	check-anchors
reads	source markdown	built HTML
markdown links with a fragment	yes	yes
raw HTML <a href>	no	yes
root-absolute links	no	yes
generated pages	not seen	seen, hence --exclude
message names	source file and source link	built HTML paths

The counts in the original report stand — both repos have zero root-absolute and
zero raw-HTML anchor links today — so the extra coverage is real but currently
unexercised. That makes this a documentation problem rather than a redundancy
problem. Option 1 is the answer:

• Fix the check_anchors.py docstring. "mkdocs build --strict does not
  validate anchors at all" was true before mkdocs 1.6 and is false now.
• State the boundary in its place, so nobody deletes the checker on discovering
  the config option: built HTML, therefore raw HTML and root-absolute links.
• Recommend validation.links.anchors: warn in the README as the cheaper first
  line of defence, noting that it names the source file, which is the more
  useful message when something does break.

One more measurement worth recording, from the same review. On halos-org/docs
check-anchors reports 1905 links across 36 pages, but 1890 of those are
same-page fragments — Material's heading permalinks, page table of contents and
sidebar navigation, all generated from the headings they point at, so they
cannot break independently. Only 15 are cross-page. Quoting the total as a
coverage figure overstates it by two orders of magnitude.