Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez,@Folyd,@jsha

This would be a new, stable feature, and honestly, I don't think we should support this. It's a niche feature and adds unnecessary UI complexity.

Niche I don't know. However it's definitely part of the markdown spec which we're supposed to follow. The problem here is that we disregarded it. Since the anchor is now displayed all the time, the UI is actually simpler in my opinion (compared to before).

I like the idea of supporting links in headers. It's good for interoperability, so you can use #![doc = include_str("../README.md")] to render the same markdown as GitHub and crates.io, both of which support this. The CommonMark spec — which we claim to support — says that the contents of headers are parsed as inlines, and links are valid inlines.

But I don't like a persistent, always-visible section link. #59840 is all about getting rid of this kind of clutter.

In rough order of my own preferences:

1. Support links in headers. Hide the section link except when you mouse over the header. Put it at the end, kinda like this, so that you don't get conflicts with the hide/show button:

   <h1 id=my-heading>My Heading<a class=section-header>&nbsp;§</a></h1>
   <style>h1 .section-header { visibility: hidden; padding: 0.25em 0; font-size: 0.5em } h1:hover .section-header, h1 .section-header:active, h1 .section-header:focus { visibility: visible }</style>
   

   The smaller font size keeps it from causing too much excessive line wrapping, even though it technically takes up space. Using visibility:hidden instead of display:none means stuff doesn't jump around when you move your mouse. And the nbsp keeps it from becoming a typographical widow, forcing the last word to wrap along with the section link.

2. If you really don't want to support links in headers, use the pulldown-cmark to actually strip them out. That way, at least we don't generate broken HTML when someone tries to use it.

   Something like this:

   struct StripLinksInHeaders<P> {
       in_header: bool,
       parser: P,
   }
   impl<P> Iterator for StripLinksInHeader<P> where P: Iterator<Item=Event> {
       type Item = Event;
       fn next(&mut self) -> Option<Event> {
           let mut n = self.parser.next()?;
           if n == Event(Start(Header)) { self.in_header = true; }
           while self.in_header && (n == Event(Start(Link)) || n == Event(End(Link))) {
               n = self.parser.next()?;
           }
           if n == Event(End(Header)) { self.in_header = false; }
           Some(n)
       }
   }
   

Since the anchor is now displayed all the time, the UI is actually simpler in my opinion (compared to before).

The click target is then very small though.

1. Hide the section link except when you mouse over the header. Put it at the end, kinda like this, so that you don't get conflicts with the hide/show button:

Hmm, but then it's in a different position depending on how long the header is.

I'd prefer to keep the anchor on the left too (because it's where it is for all other headings). A middle-ground could be to turn the visibility off by default so it keeps taking the space but is visible only when you hover the heading.

I'm inclined to close this PR since it seems like more discussion is needed. What do you think?

We don't have a tracking issue. Let's open one to continue the discussion there and then close this PR.

Ok, I opened a tracking issue and summarized my understanding of the current state of this issue: #100254

Thanks!