I often find myself trying to refer to a particular section in the Snapcraft docs and find that there’s no named anchors there (i.e. those allowing a #some-heading in the URL to scroll the browser down there).
As an example, GitHub does this automatically by creating a named anchor from the heading text itself. That would be a huge gain in itself. It also displays a icon on hover on the left of the heading to let the viewer know there’s an anchor and let them get the link for it.
With the above issue, there didn’t seem to be a simple solution, but I think it’s worth revisiting to see if we can either find a new solution (possibly a Discourse addon?), work something into the publishing backend, or maybe standardise on marking up headings to generate the deep links.
(For some reason, browsers seem to find the position of the link better if it’s the id of a header instead of the name of a link.)
The advantage of doing these explicitly is that they don’t break when you change the heading name. However I understand that readers/users also want to link to content and won’t think of creating an anchor themselves…