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).
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 uniqueids. 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
nameattribute.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
RFC:.