Crates.io: Anchor links on READMEs don't work

[kejadlen]

GitHub automatically adds anchor links to header tags, allowing links to sections inside of a README. It would be nice if this also worked on crates.io.

Compare clap on crates.io to GitHub.

[treiff]

I took a look at this, thinking it would be a pretty straight forward fix. However, I'm thinking now it's a little more involved than I originally thought. Initially, I thought the issue stemmed from ammonia as we were not allowing relative URL's to pass through.

For example:

[About](#about) 
// Renders
<a rel="nofollow noopener noreferrer">About</a>

After modifying the html_sanitizer to allow relative URL passthrough this improved things a bit as we now have the correct href.

[About](#about) 
// Renders
<a href="#about" rel="nofollow noopener noreferrer">About</a>

That said, the real issue seems to be with that actual section you are linking to doesn't have the proper id to match the fragment identifier in the href. I'm beginning to think this could be an issue with how comrak parses the markdown.

// Given the following markdown:
[About](#about)

## About

This is the about section.

// Using comrak CLI to parse outputs:
<p><a href="#about">About</a></p>
<h2>About</h2>
<p>This is the about section.</p>

As you can see above, there is no id attribute to match up with the fragment identifier #about so clicking the About link does nothing. If you were to look at how github would render the same markdown:

## About

// Renders

<h2>
  <a href="#about" aria-hidden="true" class="anchor" id="user-content-about">
    ...<svg></svg>
  </a>About
</h2>

As you can see, because of the id=user-content-about, clicking the about link would bring you to the appropriate section of the page.

I was unable to find any info in the github flavored markdown spec about this. So, I'm not really sure the magic behind this. If anyone has any thoughts, please share. Perhaps it's something to checkin with comrak?

[kejadlen]

IIRC, GitHub uses Kramdown, which has this to say about automatic header id generation: https://kramdown.gettalong.org/converter/html#auto-ids

[kivikakk]

We don't use Kramdown; we use cmark-gfm/commonmarker, and then have our own user content stack which performs transformations to add stuff like these.

A fix is up at #1129; I've added a GitHub-compatible extension to Comrak which adds anchors to headers in the same manner (it is slightly different to Kramdown's), and enabled it in this PR.

[kejadlen]

Thanks for your work on this!