Check anchor links

[StevenMaude]

MkDocs 1.6.0 now helpfully checks these, as does lychee, so we should fix those that are broken.

[StevenMaude]

There's some quirk by which ehrQL anchor links don't get picked up by lychee.

[StevenMaude]

As one example of the ehrQL failures, this define_measure fragment doesn't get detected by lychee.

There's a bit of complication with the ehrQL fragments. After a bit of thinking, I suspect that the problem might be that the fragment identifier is in an autogenerated file that's then included by the Markdown file that represents an actual page. If the fragment checker looks, it won't find it in the "page" Markdown.

Easiest way to tell would be to create two minimal test files to reproduce the issue.

That's then an underlying issue of lychee not following the not-really-standard includes.

Other ideas that are probably not to blame

• Can lychee pick out id from Markdown files? I think so, according to this commit.
• The ehrQL fragment identifier is not "standard" — Measures.define_measure versus measures-define-measure. I don't think that's to blame, as the identifier is explicitly labelled as an id attribute and shouldn't need to be inferred, unlike identifiers generated from headings (for example, MkDocs will generate an id for # My heading as my-heading)

[StevenMaude]

We've fixed most of them, but we can't easily enable the check without some kind of solution for the false positives from the ehrQL documentation.

Maybe it's worth looking around lychee's documentation and code, or even opening a lychee issue for not checking "included" files if one's not open.

[StevenMaude]

As a workaround, MkDocs might be smarter at catching the links that lychee can't correctly resolve; see comment in the PR that fixes most of these links.

If we can get rid of all the other MkDocs warnings, then we could check these with MkDocs instead.