Check broken anchors

[honzajavorek]

This is more of a suggestion or an idea for future. We already check whether links are broken. We could check if anchors we point to in our documents actually exist. Those links are valid as in that the page exists and will load in reader's browser, but if the link contains an anchor, the intention was to point to a specific paragraph.

This is something I think Docusaurus could check out of the box (MkDocs has similar features) or that could be achieved by a relatively simple script in our CI, which goes through the resulting HTML and fails if something is off. In the past I wrote a similar script for myself in Python.

[TC-MO]

I think this is in Docusaurus v3.1 based on this page. Yet another good reason to move forward in the near future to more recent version 😄

[B4nan]

yes, we just need to upgrade

[TC-MO]

I guess with the update to 3.5.2 this can be closed as we can now use Docusaurus internal link checker to check for broken anchors as well?

[B4nan]

i think we need to enable that feature explicitly, @barjin could you please check and possibly enable that?

[barjin]

Circling back to this, the linked PR enables the onBrokenLinks: 'throw' option, but... well, it uncovers lots of broken anchors.

idk whose turf it is now (@TC-MO / @honzajavorek). Looking at the errors, they seem to be correlated with the new API reference (cc @netmilk) and the explicitly specified heading ids in Markdown (Docusaurus documentation now advises to use the ### Hello World {#my-explicit-id} syntax (see docs here)).

[TC-MO]

I'll go over all the broken links and fix the docs accordingly on the PR

[honzajavorek]

Heroes! 🦸 I can help with some portion of it if you want, @TC-MO