README not rendered properly on the repository overview page (BB-7160)

Issue #5617 resolved
Petar Maric
created an issue

After visiting I've noticed README is no longer rendered properly on the repository overview page, as it has been for quite some time. It used to be parsed as ReST and then rendered as HTML, now it's rendered as pure plain text.

This has a big impact on usability as far as I can see.

Please get it back to the good olden days.


Comments (28)

  1. Dustin Hatch

    I noticed this, too. It does correctly render files called README.rst as reStructuredText, but not files called README. The documentation says "If the file is named README.txt or README and the repository language is set to Python, the file is rendered as reStructuredText."

  2. Marcus Bertrand staff

    We rolled an update last week removing the hard requirement that all Python repositories with a .txt or no extension README were being rendered as Restructured Text. If you'd like to have your README rendered in .rst, simply update the extension. We will be updating the documentation to reflect this shortly.

  3. Dustin Hatch

    Why would you make this change? It doesn't make sense and people were obviously using the old way. What benefit can this possibly have? You've removed the content detection, and now removed this; is there some newfound love for pointless file extensions?

  4. Kirill Simonov

    Renaming README to README.rst is not a great option. Python packaging tools expect README or README.txt and complain if it is missing.

    Also, ReST FAQ suggests .txt as a standard extension.

  5. Clark C. Evans

    I'm also in agreement with Dustin and Kirill. Petar's suggestion of having this configurable would be a reasonable compromise. Note that this change makes Bitbucket far less attractive for hosting open source Python projects, so I don't see why it is in Atlassian's best interest to ignore this usability issue.

  6. Scott Sharkey

    Since the README or README.txt is required for most python projects, and in that form (not README.rst), it makes no sense to make this change. Especially since file extensions in most reasonable operating systems are "merely guidelines". This will make hosting open source python projects here less than attractive. Please restore the prior behavior or at least give us an option to override.

  7. Francisco José Fernández Naranjo

    Please, revert the previous behavior.

    There are strong arguments stated in the comments. Also, ReST is designed to be readable in plain form, the files does not need an special extension because they are also plain text files.

    Anyway, looks like PyPI even requires it to enhance the description for the project.

    The 'decoration' of ReST files was a nice feature and a lot of people is using it. The total effort in renaming and adapting the current projects is probably a thousand times your effort to revert it.

    And if you have problems determining the content-type for the files, you can always ask the community for help.

    Finally, consider the potential duplication of content that can be raised by this change if people try to get the same behavior in BB and PyPI by having to files with the same content.

  8. marc.tit

    Idem as other people. It looks like a badly design decision, and at least, a poorly communicated one...

    Please, would you mind explaining your decision?

  9. Katrina Walser

    This has been fixed. Repos that have a file in their root directory will have their READMEs rendered as reST again.

    Please note that if its still not rendering, it may be due to the version of docutils that we're using. Some directives (eg. code-block) aren't supported yet. We have an open issue (#7182) to upgrade it.

  10. Log in to comment