Markdown READMEs are becoming increasingly ubiquitous for many projects. GitHub, GitLab, Bitbucket, among others, happily detect .md readme files and render them in their web interfaces. rST is nice, but is generally overkill for single-page documents (as opposed to more intricate documentation). To get something done sooner, rather than later, I'd prefer to come up with a two-phase solution, one narrow and "opt-in" (status-quo for all existing packages unless the maintainer does something) for quick implementation with hopefully minimal pushback. The other, later, not-proposed-here, could be more feature-rich/heuristic. So, to get Markdown supported in some form, here's some talking points to debate: * Add a "long_description_filename" to setup (suggested by @msabramo/GH [1]), which does the usual boilerplate "[codecs.]open(x, 'r', encoding=y).read()". To determine the format look at an additional "long_description_content_type" field (if provided), otherwise look at the file extension and assume/require UTF-8. * As an alternative, if there is no long_description, and the fall-back to README.rst fails, look for README.md and grab that. Such a strategy wouldn't be fully opt-in, however. * Markdown (just like reStructuredText) allows arbitrary HTML to be added. The renderer must then be upstream of the (existing) clean (with bleach) step. * [Optional]: Use common extensions provided by the PyPI/Markdown library to support GFM/SO stuff: fenced_code, smart_strong, nl2br Nick Timkovich Amaral Lab, Northwestern University [1]: https://github.com/pypa/readme_renderer/pull/3#issuecomment-72302732 [2]: https://github.com/pypa/readme_renderer/pull/3#issuecomment-66569248