README content

A README is a reference for other users visiting your repository and documents steps for them to get your application up and running. You can either add and edit your README file locally or straight from Bitbucket Cloud.

Add and edit a README from Bitbucket

When you create a repository, you'll see the Include a README? field.

  • If you're new to Bitbucket: We recommend that you select Yes, with a tutorial to quickly learn how to add, edit, and clone from Bitbucket.

  • If you're an experienced user: Select Yes, with a template to add content to the README with suggestions and a guidelines for the type of information to include.

If you select No, you can still pick Create a README from the repository Source page. Once you have a README, click Edit README to update your README from Bitbucket.

Format your Readme with markup

Bitbucket can parse and display MarkdownreStructuredTextTextile, and plain text README files. With a syntax like Markdown, you can emphasize text, include screen captures, and more.

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

Extensions and Languages

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. README files with a known file extension have precedence. 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. This table lists the supported filename extensions and their corresponding mark up languages:





We support the following extensions for Python-Markdowncodehilite, tables, def_list, del, footnotes, headerid, sane_lists, abbr, fenced_code, toc, wikilinks.

We don't support arbitrary HTML in Markdown, for example <table> tags.


reStructuredText (reST)





For Bitbucket wikis only, not supported with README files.


Code highlighting

If you're using Python Markdown (with .md, .mkdn, .markdown, or .text extentions), you can add code highlighting to your README. For example, the following illustrates three types of highlighting supported by Python Markdown. Keep in mind, the spacing is important.

1 2 3 4 5 ```javascript if ('' || ('wicket') > -1 &&!='wicket-wicket:default')) { window.location="register/wicket:pageMapName/wicket-0" + (window.location.hash != null ? window.location.hash : ""); } ```
1 2 3 4 5 6 ```java function foo() { int poo = 1; return; } ```
1 2 3 4 5 ```python friends = ['john', 'pat', 'gary', 'michael'] for i, name in enumerate(friends): print "iteration {iteration} is {name}".format(iteration=i, name=name) ```


Still need help?

The Atlassian Community is here for you.