rustdoc: "Namespace" user-written Markdown headings · Issue #91759 · r...

camelid commented on Dec 10, 2021 •

Tracking issue for @jsha's idea mentioned here. What follows is @jsha's summary of the idea:

When markdown like # Examples is processed, it usually turns into something like <a href="#examples" id="examples">. This is useful so you can click on the heading and get a link that will take someone else to that precise part of the docs.

Since the markdown in rustdoc is user-generated, those anchor ids may conflict with Rustdoc's own anchor ids. They may also conflict with other markdown sections within the same doc page. For instance, see:

https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples
https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples-1
https://doc.rust-lang.org/nightly/std/string/struct.String.html#examples-2

Right now we disambiguate these ids by added a number at the end. However, it would be better to disambiguate them by namespacing. Specifically, each time we render markdown we should provide a "prefix", and all IDs in the generated HTML should start with that prefix. In general a convenient and sensible choice for this prefix would be the id of the immediately preceding heading. So the examples linked above might become #top.examples, #method.new.examples, and #method.from_utf8.examples.

This has three advantages:

• It systematically removes most of the cases of id conflict.
• It makes anchor links more meaningful when someone reads the URL.
• It makes anchor links stable across revisions.

This is a 99% solution, not a 100% one. Users can author HTML directly in their markdown, for instance <div id="foo">. But we are okay with letting the conflicts happen in those rare cases.