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 REAMDE from the Overview 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 README.md as a file that uses the Markdown language. README files with a known file extension has 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:
Extension
Language

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

Markdown

We support the following extensions for  Python-Markdown codehilite, 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.

.rst

reStructuredText (reST)

.textile Textile
.wiki

Creole

For Bitbucket wikis only, not supported with README files.

If you define a setup.py file in your repository's root, Bitbucket parses files that don't have an extension or that use the .txt extension as reST. If you don't define a setup.py file, these files render as plain text.

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:

Javascript example
```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 : ""); 
}
```
Java example
```java
function foo() {
int poo = 1;
	return;
}
```
Python example
```python
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
	print "iteration {iteration} is {name}".format(iteration=i, name=name)
```

The spacing is important. This README displays as follows in Bitbucket:

Last modified on Feb 23, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.