Support internal links in markdown long_descriptions

[Oberon00]

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).

[di]

Thanks for the feature request!

One complication with this is that we currently use URL fragments on project pages to link to PyPI-specific things, e.g.:

• https://pypi.org/project/pip/#description
• https://pypi.org/project/pip/#history
• https://pypi.org/project/pip/#files

If we wanted to support this, would need to make sure that this existing behavior remains.

[tomcnolan]

I was very surprised to discover this PyPI limitation, which breaks a README.md/long_description's Table of Contents. I agree with @Oberon00 that this feature is needed for consistency between Markdown source shared between GitHub and PyPI.

[mdumandag]

Any updates on this ?

@di I see that for reStructuredText documents, anchor links are working as expected. For example, see this package. https://pypi.org/project/demandlib/ . I can easily navigate to sections using the table of contents.

[di]

I transferred this issue to pypa/readme_renderer which is responsible for rendering descriptions on PyPI.

I don't have any updates. For anyone wanting to work on this, first steps would be to determine where id/name attributes are being stripped for markdown, whether this is intentional, or can be modified, and then modifying it.

[simonw]

I just ran into this problem for my package here: https://pypi.org/project/twitter-to-sqlite/

I added a table of contents to my README on https://github.com/dogsheep/twitter-to-sqlite (using this recipe) but it doesn't work on PyPI.

[simonw]

It looks like Bleach is meant to be allowing the id attribute on every element here:

readme_renderer/readme_renderer/clean.py

Lines 36 to 43 in be206d3

	ALLOWED_ATTRIBUTES = {
	# Bleach Defaults
	"a": ["href", "title"],
	"abbr": ["title"],
	"acronym": ["title"],
	# Custom Additions
	"*": ["id"],

[simonw]

... but in poking around with the library it looks like those id=... attributes aren't present even before Bleach runs. So I think the issue is in https://github.com/theacodes/cmarkgfm

[simonw]

There's an open issue about that here: theacodes/cmarkgfm#20

[simonw]

And I think the root issue is over in github/cmark-gfm here: github/cmark-gfm#186

[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.

[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.

[Oberon00]

What about the name attribute that can be used instead of id for anchors?

[Eutropios]

What's the current workaround for this?

[hugovk]

@Eutropios #169 (comment)

[Eutropios]

@Eutropios #169 (comment)

Thank you! It'd be nice if PyPI did this automatically though 😅