Support internal links in markdown long_descriptions

What’s the problem this feature will solve? I want to set internal links/anchors in my README.md/long_description in markdown format (for example See [the documentation](#documentation) for more information which links to a ## Documentation heading or an explicit <a name="documentation"></a> anchor). Ideally I’d like to use the same internally linked Markdown source for both GitHub and PyPI.

Describe the solution you’d like Explicit link creation via <a name> and <a id> should be supported (maybe only <a name>, depending on the potential to disturb any Javascript code).

Ideally GitHub-compatible automatic anchor generation for headings should also be supported.

Additional context A GitHub README.md supports two ways of setting anchors:

• Implicitly, by generating an anchor from a heading (an <a id="lower-case-with-some-chars-replaced-by-hyphens">)
• Explicitly, by placing <a id="..."> or <a name="..."> tags.

Warehouse does not automatically generate anchors for headings. It also strips id and name attributes from HTML embedded in the Markdown file. This leaves no possibility of linking to another location within the description (without using an absolute link to PyPI.org, which is undesirable since the README is typically used in other places like GitHub too).

[vgavro]

My two cents: For now pypi doesn’t strip <a id="xxx"></a> tag, recommended way to create anchors for both github and pypi:

### Title<a id="title"></a>

(Note - no space between title and tag, otherwise you’ll have self-link 🔗 pointing “title-” instead of “title”)

BUT - it would be awesome if pypi would automatically create anchors same way as github do.

[andrewtavis]

Not sure if there have been fixes in regards to all this - maybe id tags aren’t being stripped anymore, or you simply need to add them explicitly - but the following works on both GitHub and PyPI now:

Contents:<a id="contents"></a> [Section Header](#section-header)

# Section Header [`↩`](#contents) <a id="section-header"></a>

Using ↩ in single quotes creates what to me is an intuitive/appealing back button (although it’s rendered differently on PyPI). See any of my projects for an example of how it looks/functions.