PyPI should render readmes written in Markdown

[hickford]

Reproduced from https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes

---

If you write your readme in Restructured Text, PyPI will render it on your project's page (eg. https://pypi.python.org/pypi/requests ). It should be possible to write your readme in Markdown too. Markdown is a pervasive format used on GitHub and StackOverflow. It shouldn't be necessary to learn a new markup language or rewrite your project's documentation to publish a Python package.

This is common frustration, and the Python community suffers because it's a barrier to publishing packages and writing documentation . Please consider it!

• http://stackoverflow.com/questions/10718767/have-the-same-readme-both-in-markdown-and-restructuredtext
• http://i.imgur.com/7NYlimN.png
• https://coderwall.com/p/qawuyq
  If you write your readme in Restructured Text, PyPI will render it on your project's page (eg. https://pypi.python.org/pypi/requests ). It should be possible to write your readme in Markdown too. Markdown is a pervasive format used on GitHub and StackOverflow. It shouldn't be necessary to learn a new markup language or rewrite your project's documentation to publish a Python package.

This is common frustration, and the Python community suffers because it's a barrier to publishing packages and writing documentation . Please consider it!

• http://stackoverflow.com/questions/10718767/have-the-same-readme-both-in-markdown-and-restructuredtext
• http://i.imgur.com/7NYlimN.png
• https://coderwall.com/p/qawuyq

[ncoghlan]

I believe supporting more markup languages is on the todo list for
Warehouse (behind becoming a feature complete replacement for the existing
PyPI implementation).

[hickford]

I had a go https://bitbucket.org/pypa/pypi/pull-request/33/support-markdown-for-readmes/diff

[bukzor]

hickford's change was committed, then rolled back.
This is the second attempt I think: https://bitbucket.org/pypa/pypi/pull-request/59

[karolyi]

+1

[xapple]

+1

[coxjonc]

+1 man writing rst is annoying

[pylover]

+1

[ekohl]

It would appear pypa/readme_renderer#3 is the latest effort.

[pylover]

Interesting

[msabramo]

I think the next step is to get pypa/packaging.python.org#258 reviewed.

[AnaPana-zz]

+1

[glenjamin]

Is this feature now fully merged? I tried to piece together how to make it work today, but my README ends up as plain text still.

[brainwane]

@glenjamin Sorry, no, not yet! @di is working on the checklist in pypi/warehouse#869 (comment) . Specifically, at the moment, he's working to update pkginfo. Then the next thing to fix will be twine and then Warehouse.

[sayanarijit]

Hi All

Why don't we just use client side JavaScript to automatically detect the format and render it?

There are plenty of render tools like gfm that are capable enough to handle it all at client side.

This way I believe there is no need to change any algorithm at the back-end.

[merwok]

I would be great if the new PyPI kept being functional without requiring javascript.

[ewdurbin]

Accepted PEP 566 Description-Content-Type removes the need for trying to detect the format.

Once implemented, The renderer for PyPI (https://github.com/pypa/readme_renderer) will be able to add explicit renders for various markup syntaxes. This is the correct solution and doesn't require JavaScript or other fragile hacks.

Right now most of the maintainers/contributors are working on completing the final/production rollout and switchover to https://github.com/pypa/warehouse, but I believe some progress is being made towards implementation of PEP 566 overall.

[brainwane]

Yeah, @di has been making great progress on implementing PEP 566 in relevant tools -- pypi/warehouse#869 (comment) is a good checklist to follow and he's updating it as maintainers merge and release his improvements.

There's now a release candidate for the next version of Twine available and it includes PEP 566 compliance. (Witness my test project!) Feel free to use it as you test other Markdown-related packaging ecosystem stuff.

[ncoghlan]

Given https://dustingram.com/articles/2018/03/16/markdown-descriptions-on-pypi, I'm going to go ahead and close this. Even though it will take a while for all the related updates to ripple out through the ecosystem, it now works with latest PyPI, setuptools, and twine combo :)

[hickford]

Great news, thank for sharing! To clarify, Markdown readme detection isn't automatic: you need to follow the instructions for and reupload your project.

Thanks to all involved.

[msabramo]

I was very happy to see that this happened! Fantastic! Thank you everyone who worked on this and the new PyPI!