Open Oberon00 opened 6 years ago
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.:
If we wanted to support this, would need to make sure that this existing behavior remains.
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.
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.
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.
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.
It looks like Bleach is meant to be allowing the id
attribute on every element here: https://github.com/pypa/readme_renderer/blob/be206d314d35a5d70416e4d76d55d19adcb5774b/readme_renderer/clean.py#L36-L43
... 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
There's an open issue about that here: https://github.com/theacodes/cmarkgfm/issues/20
And I think the root issue is over in github/cmark-gfm
here: https://github.com/github/cmark-gfm/issues/186
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.
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.
What about the name
attribute that can be used instead of id
for anchors?
What's the current workaround for this?
@Eutropios #169 (comment)
Thank you! It'd be nice if PyPI did this automatically though 😅
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:
<a id="lower-case-with-some-chars-replaced-by-hyphens">
)<a id="...">
or<a name="..."
> tags.Warehouse does not automatically generate anchors for headings. It also strips
id
andname
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).