Should rustdoc support links in headings?

[camelid]

Markdown allows links to appear in headings, but rustdoc doesn't (properly) support this. @GuillaumeGomez had a PR to implement this: #94360. However, supporting this feature makes other parts of rustdoc's UI worse: Currently, rustdoc makes headers link to themselves (to make grabbing a link to the header easier). If we supported user links in headers, this wouldn't work anymore. We could use “§”, but it presents a small click target and adds visual noise. So, more discussion is needed.

• Determine rustdoc's status quo for this feature
• Decide whether it makes sense to support this
  • If yes, decide how header self-links should be implemented
  • If no, decide if we should warn when users make links in headers, or if we should maintain the status quo

[jsha]

There was also some discussion at:

• https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Heading.20anchors.
• https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Anchor.20links.20on.20hover/near/271538428

I am convinced that we should allow links in headings, make headings not themselves links by default, and use a § on hover consistently for all heading self-links.

I was originally skeptical because I had hoped to find a way to eliminate the § from all our docs. I wanted that in part because it's hard to squeeze in the § in our current left-hand "gutter" (the space between the sidebar and the left side of the main text):

But now I think there's probably no good solution to that. We should either (a) increase the width of the gutter to accomodate both § and [-] or (b) move the § to the right-hand side of the first line of each heading (for instance, including it in the "source" cluster of links).

In theory this work can proceed without fixing the issue of § placement for code headings. But there's on place where we have a similar conflict: When the first line of a Markdown block is a heading, there's a [-] to its left. Adding a § in between the [-] and the heading will look cramped. And adding space for the § to breathe means the [-] will look like it's floating in space most of the time.

[GuillaumeGomez]

Something we could potentially try would be to display § all the time. That would allow it to work on mobile devices. However it would make the display a bit heavier.