If your repository contains a
README file at the root level, Bitbucket displays its contents below on the repository's Overview page. Bitbucket can parse and display Markdown, reStructuredText, Textile, and plain text
README files. With a syntax like Markdown, you can emphasize text, include screen captures, and more.
For a tutorial Bitbucket's Markdown support, including syntax examples, see our Markdown demo repository.
This page contains the following information:
File naming and precedence
The file extension you use with your README determines how Bitbucket parses the markup in your file. For example, Bitbucket interprets the
README.md as a file that uses the Markdown language. Filename extensions have precedence. Meaning, if you have multiple
README files with different file extensions, Bitbucket takes the first file that matches a known format.
With the exception of Creole markup, Bitbucket supports the same markup in README files as it does in wiki files. The table below lists the supported filename extensions and their corresponding mark up languages:
We support Python-Markdown. Please note, we don't support arbitrary HTML in Markdown, for example
We support version 0.7 markup. We have a pending issue to upgrade to the latest version. You can vote on that here. The
For Bitbucket wikis only, not supported with README files.
If you have a defined a
setup.py file in your repository's root, Bitbucket parses files without an extension or that use the
.txt extension as reST also. If you do not define a
setup.py file, these files render as plain text.
Highlighting code syntax for Python Markdown
If you are using Python Markdown (.md, .mkdn, .markdown, or .text), you can add code highlighting to your Markdown README. For example, the following illustrates three types of highlighting supported by Python Markdown:
The spacing is important. This README displays as follows in Bitbucket:
Wondering if we support a feature?
This documentation does not reproduce the Markdown, reStructuredText, and Textile documentation; we only document the known limitations. Wonder what these markup languages can do? Then, you should visit to their sites and read their documentation. Then, just try it out in your README.
Limitations of Markdown
If you are using Markdown for your README, Bitbucket has the following limitations:
For security reasons, we do not allow arbitrary HTML in Markdown README files.
In the past, one could override the format detection by adding a special comment to the top of the file like this:
Bitbucket removed support for preambles in favor of using the format's appropriate file extension.
Improving our README feature
There are a lot of ways to improve our README feature. If you want to request an enhancement or feature, the best place to do this is in our issue tracker. The development team does not always follow or respond to comments on the documentation pages.
This query here shows you all the outstanding README issues on our tracker.