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.
- README
- README.markdown
- README.md
- README.mkdn
- README.rst
- README.textile
- README.txt
- READ.ME
- readme
- readme.markdown
- readme.md
- readme.mkdn
- readme.rst
- readme.textile
- readme.txt
- read.me
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.