Dress up your repository with a README

By on May 13, 2011

Have you ever thought it strange that Bitbucket displays READMEs on the “source” screen rather than the “overview” screen? Many repositories have the landing page set to “source” to accommodate this quirk.

The natural home for READMEs is the overview screen, so we’ve made this change. In the short term, we’ll continue to display READMEs on the source screen as well, to give those who wish to switch their landing pages to “overview” time to do so.

We’ve also expanded the list of accepted README file names. The full list appears below, with new options in bold.

We’ve also applied Django’s

urlize

filter to plaintext READMEs to provide automatic hyperlinking.

READMEs are a great way to encourage users to try your software. Mezzanine, a Django CMS hosted on Bitbucket, uses reStructuredText to take advantage of headings, bulleted list, embedded images and links to dress up its README.

If you prefer to kick it old school, there’s no shame in including a plaintext README. PyPy, for example, does just this.

  • Stefan

    Nice feature. But it would be great if README.txt files would also be rendered as reStructuredText. PiPy, for example, does just this. And the Hitchhikeru2019s Guide to Packaging also recommends using README.txt.

  • Stefan

    Nice feature. But it would be great if README.txt files would also be rendered as reStructuredText. PiPy, for example, does just this. And the Hitchhiker’s Guide to Packaging also recommends using README.txt.

    • http://notatnik.mekk.waw.pl Mekk

      Me too ;-) For PyPi I keep top-level README.txt in reStructuredText, would be nice if bitbucket handled the same.

      • http://davidchambersdesign.com/ David Chambers

        One option, @openid-18279:disqus, is to use README.rst in both places. This should work on PyPI provided that you update setup.py accordingly.

        In the future we may make it possible to specify a README’s format explicitly, rather than relying on its file extension. I’m not yet convinced, though, that the flexibility this would provide warrants the inclusion of an additional UI element.

  • Stefan

    Nice feature. But it would be great if README.txt files would also be rendered as reStructuredText. PiPy, for example, does just this. And the Hitchhiker’s Guide to Packaging also recommends using README.txt.

  • http://davidchambersdesign.com/ David Chambers

    Thanks for the suggestion,u00a0@c1d1a92af71a5bbcc4c54fd1a2c19e84:disqus. I’m unfamiliar with reStructuredText, so bear with me. Are you suggesting that we treat _all_ .txt READMEs as reStructuredText, or that we do so only for those that identify themselves as such via a document header?

  • http://davidchambersdesign.com/ David Chambers

    Thanks for the suggestion, @c1d1a92af71a5bbcc4c54fd1a2c19e84:disqus. I’m unfamiliar with reStructuredText, so bear with me. Are you suggesting that we treat _all_ .txt READMEs as reStructuredText, or that we do so only for those that identify themselves as such via a document header?

    • Stefan

      David,

      I would try to handle all README.txt als reStructuredText. If the parser fails, they can still be displayed as plain text. If you also cache the results of that process until the README.txt is updated again, the performance impacts wold imho be quite low. Afaik, it’s not possible to mark a txt-file with a header as ReST.

      Cheers,
      Stefan

      • Tom

        I have a README.txt that used to be processed as reStructuredText. Now it displays as plain text. It’s a private site (https://bitbucket.org/uwlabmed/tracker/overview) but I can send you the README.txt file if you want to see it.

  • http://davidchambersdesign.com/ David Chambers

    Thanks for the suggestion, @c1d1a92af71a5bbcc4c54fd1a2c19e84:disqus. I’m unfamiliar with reStructuredText, so bear with me. Are you suggesting that we treat _all_ .txt READMEs as reStructuredText, or that we do so only for those that identify themselves as such via a document header?

  • Anonymous

    This is neat. Please also consider giving the code samples in the README in <pre> tags a slight background so that they can be distinguished from the normal text.nnThanks,nShantanu

  • Anonymous

    This is neat. Please also consider giving the code samples in the README in <pre> tags a slight background so that they can be distinguished from the normal text.

    Thanks,
    Shantanu

    • http://davidchambersdesign.com/ David Chambers

      Thanks @kumarshantanu:disqus. I’m looking forward to improving the styling of code snippets throughout the site. Now that I’m adding READMEs to my various projects I have a strong incentive to do so!

  • Anonymous

    This is neat. Please also consider giving the code samples in the README in <pre> tags a slight background so that they can be distinguished from the normal text.

    Thanks,
    Shantanu

  • Jgpallero

    It would be nice if other file names instead README were accepted. This can be done with an option in the admin tab, for example

  • Jgpallero

    It would be nice if other file names instead README were accepted. This can be done with an option in the admin tab, for example

  • Jgpallero

    It would be nice if other file names instead README were accepted. This can be done with an option in the admin tab, for example

    • http://davidchambersdesign.com/ David Chambers

      Are you able to provide an example? Is it non-English equivalents you would like to be able to use?

      • Jgpallero

         I suggest that the name of the readme file, instead of a list of possible names, would be provided with a configuration variable in the “admin” tab of the repository, so we can use each name in each language. The format of the readme (reStructuradText, for example) coul be detected internally via the extension or magis numbers

  • Guest

    Could you add asciidoc format?

  • Guest

    Could you add asciidoc format?

  • Guest

    Could you add asciidoc format?

    • http://davidchambersdesign.com/ David Chambers

      I’ll create an internal issue for this request, but it won’t be a high priority. I suggest checking out reStructuredText (which is similar) if you’d like your READMEs to be rendered as HTML.

      • Christian Kyony

        Hi David,

        I know that asciidoc format is not high in your priority list. But two years have passed. When are you going to include asciidoc?

        • http://davidchambersdesign.com/ David Chambers

          I’m no longer on the Bitbucket team, but hopefully someone will jump in to give you a status update. If not, I suggest opening an issue on the public issue tracker.

          • Christian Kyony

            Thank you David for your prompt reply.

          • apotheon

            First Note To Self: When creating a new code hosting site, include support for asciidoc in README files.

            Second Note To Self: When visitors to the site’s blog are already signed in on the site, allow use of that identity for comments rather than forcing logins via some third-party service or “anonymous”/”guest” comments.

  • Anonymous

    There seems to be an issue when rendering textile files. It doesn’t seem to work. Take a look atu00a0https://bitbucket.org/rodolfocaldeira/mercurial-sandboxnu00a0

  • Anonymous

    There seems to be an issue when rendering textile files. It doesn’t seem to work. Take a look at https://bitbucket.org/rodolfocaldeira/mercurial-sandbox
     

  • Anonymous

    There seems to be an issue when rendering textile files. It doesn’t seem to work. Take a look at https://bitbucket.org/rodolfocaldeira/mercurial-sandbox
     

    • http://davidchambersdesign.com/ David Chambers

      Thanks very much for the heads-up, and for filing a bug report. We’ll update https://bitbucket.org/site/master/issue/2816/readmetextile-files-are-not-being-parsed once we’ve deployed a fix.

  • Martin Velez

    Can you add support for RDOC?  Many of my projects are in Ruby?  Can we contribute?

    • apotheon

      I emphatically second this request.

      • apotheon

        Odd how asciidoc has received more attention than rdoc in the last two years (and still no progress there, either) . . .

    • http://www.facebook.com/ardeearam Ardee Aram

      +1

  • Mattslay

    It would be nice if it also supported the basic wiki syntax that we use to edit the wiki pages. I’m already pretty familiar with that one. No need to have to learn another.

  • bob zhang

    Can you add support for emacs org mode?

  • Macropus

    Does this still work? I can’t see my Readme.md displayed anymore.

  • Matthis Thorade

    Could you give examples how to link to the issues page from the readme.md using relative paths? Or to the downloads/tags page, …?

  • Rob

    Is it possible to have multiple readme files in one repository? or a readme file that links to another file that will also support markdown? need to document more than will fit in a single pager…

    thanks.

  • Matt

    There should be a setting for displaying the readme at the top or bottom, as if the readme contains important info then it would be handy to show it before the files.

  • Stefan

    David, nnI would try to handle all README.txt als reStructuredText. If the parser fails, they can still be displayed as plain text. If you also cache the results of that process until the README.txt is updated again, the performance impacts wold imho be quite low. Afaik, itu2019s not possible to mark a txt-file with a header as ReST.nnCheers,nStefan

  • Stefan

    David,

    I would try to handle all README.txt als reStructuredText. If the parser fails, they can still be displayed as plain text. If you also cache the results of that process until the README.txt is updated again, the performance impacts wold imho be quite low. Afaik, it’s not possible to mark a txt-file with a header as ReST.

    Cheers,
    Stefan

  • http://davidchambersdesign.com/ David Chambers

    Thanksu00a0@kumarshantanu:disqus. I’m looking forward to improving the styling of code snippets throughout the site. Now that I’m adding READMEs to my various projects I have a strong incentive to do so!

  • http://davidchambersdesign.com/ David Chambers

    Thanks @kumarshantanu:disqus. I’m looking forward to improving the styling of code snippets throughout the site. Now that I’m adding READMEs to my various projects I have a strong incentive to do so!

  • http://mekk.waw.pl/mk/index Mekk

    Me too ;-) For PyPi I keep top-level README.txt in reStructuredText, would be nice if bitbucket handled the same.nn

  • http://notatnik.mekk.waw.pl Mekk

    Me too ;-) For PyPi I keep top-level README.txt in reStructuredText, would be nice if bitbucket handled the same.

  • http://davidchambersdesign.com/ David Chambers

    One option,u00a0@openid-18279:disqus, is to use README.rst in both places. This should work on PyPI provided that you update setup.py accordingly.nnIn the future we may make it possible to specify a README’s format explicitly, rather than relying on its file extension. I’m not yet convinced, though, that the flexibility this would provide warrants the inclusion of an additional UI element.

  • http://davidchambersdesign.com/ David Chambers

    One option, @openid-18279:disqus, is to use README.rst in both places. This should work on PyPI provided that you update setup.py accordingly.

    In the future we may make it possible to specify a README’s format explicitly, rather than relying on its file extension. I’m not yet convinced, though, that the flexibility this would provide warrants the inclusion of an additional UI element.

  • http://davidchambersdesign.com/ David Chambers

    Are you able to provide an example? Is it non-English equivalents you would like to be able to use?

  • http://davidchambersdesign.com/ David Chambers

    Are you able to provide an example? Is it non-English equivalents you would like to be able to use?

  • Jgpallero

    u00a0I suggest that the name of the readme file, instead of a list of possible names, would be provided with a configuration variable in the “admin” tab of the repository, so we can use each name in each language. The format of the readme (reStructuradText, for example) coul be detected internally via the extension or magis numbers

  • Jgpallero

     I suggest that the name of the readme file, instead of a list of possible names, would be provided with a configuration variable in the “admin” tab of the repository, so we can use each name in each language. The format of the readme (reStructuradText, for example) coul be detected internally via the extension or magis numbers

  • http://davidchambersdesign.com/ David Chambers

    I’ll create an internal issue for this request, but it won’t be a high priority. I suggest checking out reStructuredText (which is similar) if you’d like your READMEs to be rendered as HTML.

  • http://davidchambersdesign.com/ David Chambers

    I’ll create an internal issue for this request, but it won’t be a high priority. I suggest checking out reStructuredText (which is similar) if you’d like your READMEs to be rendered as HTML.

  • http://davidchambersdesign.com/ David Chambers

    Thanks very much for the heads-up, and for filing a bug report. We’ll updateu00a0https://bitbucket.org/site/master/issue/2816/readmetextile-files-are-not-being-parsed once we’ve deployed a fix.

  • http://davidchambersdesign.com/ David Chambers

    Thanks very much for the heads-up, and for filing a bug report. We’ll update https://bitbucket.org/site/master/issue/2816/readmetextile-files-are-not-being-parsed once we’ve deployed a fix.