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 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 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 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:
Extension | Language |
|---|---|
.md | 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. |
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.
JAVASCRIPT EXAMPLE
1
2
3
4
5
```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
1
2
3
4
5
6
```java
function foo() {
int poo = 1;
return;
}
```PYTHON EXAMPLE
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)
```
Was this helpful?