Display README text on the overview

If your repository contains a README file at the root level, Bitbucket Cloud 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  and the following extensions codehilite, tables, def_list, del, footnotes, headerid, sane_lists, abbr, fenced_code, toc, wikilinks. However, 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 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:
Extension
Language

.md
.mkd
.mkdn
.mdown
.markdown 
.text 

Markdown

We support Python-Markdown  and the following extensions codehilite, tables, def_list, del, footnotes, headerid, sane_lists, abbr, fenced_code, toc, wikilinks. However, 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.

.rst

reStructuredText (reST)

.textile Textile
.wiki

Creole

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:

python
This is a random Javascript:    

        :::javascript
        if (window.name=='' || (window.name.indexOf('wicket') > -1 && window.name!='wicket-wicket:default')) { 
        window.location="register/wicket:pageMapName/wicket-0" + (window.location.hash != null ? window.location.hash : ""); 
        }

This is some very random Java:

    :::java
        function foo() {
            int poo = 1;
                return;
        }

Here is some random Python

    :::python
        friends = ['john', 'pat', 'gary', 'michael']
        for i, name in enumerate(friends):
            print "iteration {iteration} is {name}".format(iteration=i, name=name)

Try your own!

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:

HTML

For security reasons, we do not allow arbitrary HTML in Markdown README files. 

Preambles

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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport