Skip to end of metadata
Go to start of metadata

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.

Now you can edit your README file with just a single click from the Overview page. Just look for the Edit README link above your README.

For a tutorial Bitbucket's Markdown support, including syntax examples, see our Markdown demo repository.

This page contains the following information:

We support Python-Markdown. Please note, we don't support arbitrary HTML in Markdown, for example <table> tags. Instead, we use safe mode. Safe mode requires that you replace, remove, or escape HTML tags appropriately.

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 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 <table> tags. Instead, we use safe mode. Safe mode requires that you replace, remove, or escape HTML tags appropriately.

reStructuredText (reST)



For Bitbucket wikis only, not supported with README files.

If you have a defined a 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 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 MarkdownreStructuredText, 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:

-*- markdown -*-

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.



  1. The comments on this page were incorporated and then removed. They were preserved in their original form as an attachment. Some of the comments were feature requests, which leads me to this point:

    (minus) Before you request a feature you should review the outstanding feature requests for readmes then, bump or follow those you think are important. If you don't see what you want, create an issue on the tracker. Comments on this page are not always read by dev and the most efficient way to get noticed (really) is through the tracker.

  2. Anonymous

    The "Python Markdown" link now links to, please update this page.

    1. Thank you for the catch!  This is fixed.

      1. Anonymous

        I am trying to stop watching this page and stop getting notifications for it, but when I click the links in the email to do so, I get a 404 error from Atlassian's site.  Please correct this so I can stop getting these mails.

        1. Hi, I can remove you if you tell me what your username is or email.  If you want, email me with it rather than broadcasting


  3. Anonymous

    Do you also support the footnotes extention?

    1. Anonymous

      NVM, I figured I just tried it out, and it does (smile)

  4. Anonymous

    Sad to see you don't support Creole for README. It's already supported for wikis and it was first wiki syntax you support.

  5. Anonymous

    How do I turn off syntax highlighting for particular code blocks? I need this to display a shell session, and whenever there are quotes, it just messes the whole syntax highlighting. There seems to be minimal documentation on this.

    1.  You should probably use preformatted text to show a shell session.  To do this, indent each line by 4 characters.  Here is an example of what that looks like:

      I'm afraid documenting the syntax of all the different markup languages we support is just not something I've got the bandwidth to do.  Your best bet is to go to that languages home page and see what they recommend.  

    2. Anonymous

      In your example, the syntax of the shell session is still highlighted.

      I do not want any syntax highlighting at all. Is this possible?

    3. Anonymous

      The issue is that syntax highlighting is not part of standard Markdown syntax, and since Bitbucket is using Python's CodeHilite extension, I at least expect to be able to use CodeHilite's documentation. However, there's no way for me to turn off syntax highlighting using their documentation (most bottom part of the documentation; by passing the guess_lang argument as False), and CodeHilite's documentation is also minimal.

      1. You might want to just put your examples on lines by themselves and not inset them.  If you want a lot of formatting control, Markdown is pretty limited.

    4. My two cents: You can use php as syntax without providing the <?php open tag. Without it, no coloration. For sure, it's a hack but works very well.