Skip to end of metadata
Go to start of metadata

Bitbucket allows you to use Markdown syntax any place in the user interface where you can enter a comment.  For example, line commenting, pull request comments and change set comments.  You can also use Markdown when creating issues on the issue tracker. There are also some special things you can do like link to external websites or Bitbucket issues and pull requests — and a lot more.  

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

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.

A short peek at Markdown in action

Markdown syntax allows you to create some fancy comments. You can type Markdown by hand or use our comment bar:



Linking to Bitbucket Objects from Comments and Commit Messages

You can also refer to a Bitbucket issues, requests, and users directly from a comment or issue or commit message.  When you create a reference, saving the comment (or issue) causes Bitbucket to automatically link to that object.  For items that relate to a repo, such as issues, pull requests, and commits, markdown references to Bitbucket objects always refer to the current repository.  You can also mention an individual or team account — even insert an emoji.

Linking to objects for comments and issues within a repository
pull request
pull request #PR_NUMBER
pull request #29
issue #3


7-40 chars


Linking to non-repository objects
user (account)


David Coffey created a list of available emoji.  




Finally, if you have created a link to JIRA or another service such as Jenkins, you can enter references for those "linkers" too.  For information on creating and using linkers, see Link to a web service.


  1. Is there a way to automatically create an issue from a comment? If reviewing code and adding a comment, is it possible to convert it (or create simultaneously) an issue?

    1. Anonymous

      I would also like to know about this

      1. Currently, no, you can't create an issue from a comment.  You can request this feature.

        1. Added enhancement request #7039

  2. Anonymous

    Is there a way to link a wiki page from issue description or comments? I'm ending up copy-pasting full wiki page URL's. 

    1. Anonymous

      Second this - would be quite natural, and useful, and frankly I'm surprised it's not supported.

    2. Anonymous

    3. Anonymous


      The [..].(...) syntax is highly unwieldy for linking from page to page.

      [[link: ....]] would be non-standard for Markdown – but I'll for non-standard if the standard is too costly to even use Markdown for a wiki...

    4. Anonymous

    5. Anonymous

  3. Anonymous

    Can we link across repositories?  It would be very convenient to have a shorthand for referring to issues and pull requests in other repositories (similar to InterTrac, but hopefully better).

    1. We can't do this yet.  It is on the list to do at some point.

      1. Is this feature request being tracked somewhere public? I looked at and couldn't see anything there.

  4. It seems lists are rather poorly supported in the issue tracker:

    • lists of lists do not work,
    • non-numeric ordered lists do not work, and
    • mixed lists (unordered within ordered and vice versa) do not work.

    Very disappointing. (sad)

    1. Anonymous

      Lists of lists don't work in Markdown...

      1. Anonymous

        Then why is there an example of this in the article? This seems like a necessity.

        1. Which example shows a list of lists?

          1. Look above in the Formatting Text and Characters section: There are examples of nested ordered, unordered, and mixed lists, along with the instructions, "Make sure you indent sub-lists 4 spaces." You give examples and instructions for a feature that does not exist.

            While it is true that nested lists aren't a feature of the original Markdown, they are included in many Markdown derivative implementations. Also, they are super useful.

            1. Doug,

              A nested list is something else to me than a list of lists.  I think of a lists of lists as similar to "a list of tables" that appear in some documents.  IOW, show me every page that contains a list.  

              I've no idea what discussions went into our current choice of Markdown implementation.  You can always file an enhancement request and make a case.


              1. Feel free to call me an idiot, but nested lists work just fine on Bitbucket. I just tried and it worked.

                I could swear I tried this earlier and they didn't work. That was the whole reason I came to this page and jumped into this conversation in the first place!

                Anyway, thanks for your time and nevermind!

                1. Doug,

                  My apologies. I missed that nested lists weren't working for you.  If you run into the problem again, please let me or support know. 



  5. Anonymous

    Why do you use other syntax then for wiki? It's really confusing and annoying to learn two very different syntaxes....

    Also it will be great to turn syntax off and keep user entered formatting as is.

    1. Anonymous

      +1 it would be very nice to have access to the same formatting both places

      1. We support Markdown in comments and multiple languages in a Wiki. We do this because many customers want Creole for their Wiki.  If you like, you can set your Wiki to use Markdown.

  6. Anonymous

    It would be very nice to be able to type the names of Python magic functions, whose names begin and end with two underscores. For example, _ _ init _ _ (without spaces in the actual code, of course). Currently these are rendered as bold.

    1. Anonymous

      You should be able to escape these by writing \_\_init\_\_ - I've just tried it while commenting some code and it works for me. In general, you can escape any Markdown specific symbol with a backslash, to explicitly get that symbol in your output.

    2. You should be able to wrap inline code with the back-tick character. For example, it would like this:

      The `__init__()` method constructs an class instance.


  7. Anonymous

    Edit, History or Delete links don't works propery with the page which title includes piriod.

    ex) Node.js

    1. This sounds like a bug.  Just to be sure, please go ahead and send an issue to and explain the situation.

  8. Anonymous

    Why cant we make a break line without having to use 2 empty lines in the issue description ?

    Instead of simply breaking a line, we are forced to have paragraphs. But here it breaks works fine. Example:

    `I am on line 1
    break (shift+enter). line 2`

    `I am on line 1

    empty (enter). line 2`

    1. You know, I don't know the answer to this.  I've searched our system to see if this was a known issue or if there was any planning around changing it.  I don' t see any thing.  I recommend that you file an enhancement request.

  9. Anonymous

    My bitbucket project contains a list of files that are stored inside the project's repository. I want to arrange the links to these files in a table-wise fashion on the project's wiki page .

    I wouldn't be surprised if wiki markup doesn't support that, but I'm unsure. In any case I didn't find how to do that with wiki markup, so I tried to inline HTML table code. This didn't result in a table, but in verbatim presentation of the HTML code.

    Could someone please enlighten me about whether it is at all possible? If so, I'd appreciate very much some directions.

    Thanks in advance,

    Erik Leunissen.

  10. Anonymous

    Looking good....but

    a) Linking between pages needs some work before Markdown can be used for wikis.

    b) Lists within lists don't look right.

    Eager as heck to use it once those issues are solved.

    Thanks for the hard work!

  11. Anonymous

    This page should include the syntax for how to hyperlink to another wiki pages.

    1. I was here looking for the same information... the syntax that solved this for me in markdown was [Page](Page) where "Page" is the name of the wiki.

  12. Anonymous

    Is there anyway to prevent urls from being automatically parsed and turned into a link? I want to display a url as text, not as a clickable link.

    1. Put the link in a code block.

  13. Anonymous

    Cannot create anchor inside page. Thus I cannot create link to anchor place I want. For example, I need a table of content for the page, but cannot.

  14. Anonymous

    Can't create internal anchor so can't create table of content...

    Does we really are in 2013 ??? wiki page here looks like 2000 year webpage.

  15. Anonymous

    Can wiki syntax be used in commit messages? It works for me on issues, but in commit messages I just see plain text without rendering of wiki markup at all... (sad)

  16. Anonymous

    Is there a way to format a block of code that spans multiple lines?

    `for ((i=0; i<8; i++)) {`
    `echo ""`
    `sleep 0.05`

    doesn't seem to work, nor does backticks at the beginning and end of the block. It sticks it all on one line.

    1. You can do this:


      for ((i=0; i<8; i++)) {
      echo ""
      sleep 0.05

      You use let the comment format bar to get this in place:

      1. Cut and paste or type the code into the comment. 
      2. Select the code.
      3. Press  button.
        A language dialog displays. 
      4. Enter the language type in the dialog.
      5. Press OK.
      1. Anonymous

        So three backticks (```) on their own line before and after the block?

        Do I need to specify a language?

        1. I checked the Markdown documentation; it doesn't appear that you need to specify a language.

  17. Anonymous

    How can I use tables?

    1. Sadly, the core Markdown doesn't support tables.

    2. Not ideal, but an okay workaround is to use text formatted as a table.

    3. Anonymous

      | Tables | Are | Cool |
      | ------------- |:-------------:| -----:|
      | col 3 is | right-aligned | $1600 |
      | col 2 is | centered | $12 |
      | zebra stripes | are neat | $1 |
  18. Anonymous

    To link from page to page is as easy as [[Page Title]]

    1. Our comment system doesn't support linking to a Wiki page from comments.

  19. Anonymous

    easy question: how can i link to a file in repos from wiki?

    also [[page name]] doesn't work for me! even with simple page names like abc or 123!


    Thanks (smile)

    1. You need to check the language setting on your wiki page. The bracket syntax works for Creole but not for Markdown.  

      If you are using Creole markup, you can link to a file using this syntax:

      <<file filename>>

      See the Macro Reference for Creole Markup for more information on using Creole with your Bitbucket wiki. 

  20. Is there a way to put a link in a sourcecode comment block that can be opened?

    It would be nice if the first comment in a class could link to it's wiki page for quick reference.

    1. You can put an HTTP address in a commit message and the system will display it as a link.

      1. I was thinking more in the XML comments in the sourcecode itself. I'm in the planning stages of another project that I'd like to make open source. If I could put a link to the project homepage in the header of each source file it would be nice if it was clickable.

        1. That is pretty cool idea. We don't do that of course but you could file an enhancement request for it.

  21. Anonymous

    Any chance that we will see a possibility to make text striked (like this)?

    I have tried jira's and github approaches. both do not work

    1. Anonymous

      I agree. Striked-through text would be helpful when updating Issue descriptions for issues that are slightly resolved but still in progress.

    2. We don't have any plans to extend Markdown.  We recommend that you lobby the creators of Markdown for this feature. The library that we depend on for our markdown implementation is this

      1. Just as an FYI, I found an extension to Python-Markdown to add this feature:

        1. Gordon, your best bet is to request this feature on our issue tracker. The team can then prioritize it and other users can vote it up.

          1. No worries. Doesn't affect me directly, but I'll submit a feature request so people can vote for it.

  22. Anonymous

    The markdown language is OK, but its really annoying to have to add two spaces to the end of each line to make new lines. This is OK for a wiki, but for comments in the issue tracker, really gets in the way and I need to constantly edit my comments to make them formatted.

  23. Anonymous

    Bulleted lists din't work:

    Example of a bulleted list
    * Some item

    * Another Item

    What is get is :

    Example of a bulleted list Some Item Another item

    1. I've just tested a bulletted list in a comment. It works fine.  Can you please explain were you typing this, cut/paste from a file, or using the toolbar?

      1. Anonymous

        it works in a comment, but doesn't work in an issue description

        1. I used the editor toolbar and it worked for me: 

          Are you hand coding these or using the toolbar?

    2. Anonymous

      Works for me only if I leave a blank line between regular text and a bulleted item

      1. Anonymous

        Same for me. Bulleted lists on an issue or issue comment only work if there is a blank line before the bulleted list start. The bulleted list button on the toolbar does not add the blank line. 


    3. I also have this problem (I use Google Chrome in Linux Mint). When I try to make bulleted lists, I get all text in one line, with some of it in Italic.

      To get a list I need to add extra paragraphs before and after the list.

      Is it possible that this is a problem with Linux line ends? (Having just a \n instead of \r\n?)

  24. In reviewing a pull request I was trying to comment on a line in a java source file to say that an "@see" reference would be useful, but markdown treated it as a user account reference.  I couldn't find any way to use an "@" – &#64; is escaped and appears as the entity reference, not the entity.  

    Markdown extensions that allow backslash \@ escaping did not work either. Is there any way to write "@see"?

    1. You can only use @ to do a user mention.  You can reference Bitbucket objects in the same repository using this syntax:

      pull request
      pull request #PR_NUMBER
      pull request #29
      issue #ISSUE_NUMBER
      issue #3


      7-40 chars


    2. seem like no way to do that (sad)

  25. You are right. Thanks for pointing this out. I've fixed the problem.

  26. Thanks for the quick update. On the other hand, the TOC on the demo repository page doesn't seem to work for me. Given that it's a long page, it takes me some time to scroll down to the code syntax part, which is what I usually need to look up.

    1. Hi Alex! Broken link. Should be quicker now.

  27. In my didn't work user linking to me (like @Jan1337z) ... why?

    1. Jan, you can't do this in a README only in comments or commit messages. 

  28. Anonymous

    Could somebody please document the [[ Wiki page ]] syntax? Because that should be exactly in that table up there and not hidden away in the bug tracker and here in the comments. Thanks.

    1. We have the syntax examples and instruction on another page linked from the top of this page (For a tutorial Bitbucket's Markdown support, including syntax examples, see our Markdown demo repository.) I will think about ways to make this more clear.

      Thank you for your comment.

      1. The Markdown demo repo is great, but it still doesn't mention the [[wiki page title]] link syntax. You have to read all these comments to find out it's even possible to link between wiki pages in Markdown.

  29. Anonymous

    VDO not available.

  30. Anonymous

    Hi I would like to write an actual @ in my comment without creating a link... is that even passible?

    1. Yes strongly agree. I've just passed a comment in a pull request with the word 'param' after the (at) symbol as I was talking about docblock comments and it brought in a user with that username. I sincerely hope the poor chap didn't get spammed as a result.



    2. Hey,

      Thanks for commenting!

      If you have a character right next to the 1@ symbol it will resolve without the Dan Stevens [Atlassian] mention. This allows you to enter email addresses and the like. 

      You can also use the code block markdown, or just click the button in the following figure: 

      The Markdown demo repository has some great examples of more complex code blocks.

      Hope this helps!

      Happy coding!

  31. Anonymous

    The video tutorial doesn't exist anymore.

  32. Anonymous

    "(Our Wiki feature does not yet support Markdown.)" - this does not seem to be true any more, given that I can select "Markdown" for my wiki.

  33. Hi,

    is it possible to refer to a previous comment from within a comment? If I have for example an issue with three comments, and, in the fourth comment, I want to refer to the comment number two, can I do this?

  34. Hello, 

    I am experimenting with my private build server, and have discovered that TeamCity actually includes build status icons in its REST api.

    However, I cannot get the image to work in my The markup is like this: 

    ![Build Status](http://Server_Address/app/rest/builds/buildType:id:Build_Configuration/statusIcon)

    But it renders to html like this: 

    <p><img alt="Build Status" src="" /></p>

    What could be the reason?