[RFC]: add link elements to README section headings to allow linking to that section

[kgryte]

Description

This RFC proposes adding link elements to README section headings to allow linking to that section.

This would be similar to how GitHub displays a link icon on hover which supports creating a link to that specific section.

One issue, however, is that package README HTML fragments are generated outside of the React application, so we'd need to either

a. add <a> tags before all headings in the original Markdown files. We do this for some READMEs now, in order to cross-reference particular sections within the same Markdown file.
b. modify the fragment generation process to insert <a> tags before headings and assigning headings unique ids.
c. manipulate the DOM on fragment load from within the React app.

From a runtime performance perspective, my preference would be for (a) or (b).

Our practice for (a) is somewhat problematic as we rely on the deprecated name attribute.

For (b), we'd need to perform some processing of the generated HTML, which could be beneficial as we could generate readable heading ids for function signatures and methods.

Accordingly, I think I'd lean toward approach (b).

Related Issues

No.

Questions

No.

Other

No.

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.