Mark up comments

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
Object Syntax Example
pull request
pull request #PR_NUMBER
pull request #29
issues
issue #ISSUE_NUMBER
issue #3

commit

7-40 chars

HEX_CHARS
bb21047
Linking to non-repository objects
Object Syntax Example
user (account)
@USERNAME
@tutorials

Emoji

David Coffey created a list of available emoji.  

:EMOJI:
:mask:


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.

Was this helpful?

Thanks for your feedback!

91 Archived comments

  1. User avatar

    Jimmy Bonney

    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?

    11 Oct 2012
    1. User avatar

      Anonymous

      I would also like to know about this

      05 Mar 2013
      1. User avatar

        manthony

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

        05 Mar 2013
        1. User avatar

          Craig Aschbrenner

          Added enhancement request #7039

          12 Apr 2013
  2. User avatar

    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. 

    11 Oct 2012
    1. User avatar

      Anonymous

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

      15 Oct 2012
    1. User avatar

      Anonymous

      +1

      06 Dec 2012
    1. User avatar

      Anonymous

      +1

      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...

      12 Jan 2013
    1. User avatar

      Anonymous

      +1

       

      07 Feb 2013
    1. User avatar

      Anonymous

      +1

      12 Feb 2013
  3. User avatar

    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).

    31 Oct 2012
    1. User avatar

      manthony

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

      31 Oct 2012
      1. User avatar

        Grzegorz Adam Hankiewicz

        Is this feature request being tracked somewhere public? I looked at https://bitbucket.org/tutorials/markdowndemo/overview and couldn't see anything there.

        18 Dec 2014
  4. User avatar

    Alexander Sideropoulos

    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)
    --ap

    17 Nov 2012
    1. User avatar

      Anonymous

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

      06 Dec 2012
      1. User avatar

        Anonymous

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

        19 Dec 2012
        1. User avatar

          manthony

          Which example shows a list of lists?

          19 Dec 2012
          1. User avatar

            Doug Waldron

            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.

            17 Jun 2013
            1. User avatar

              manthony

              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.

              Mary

              17 Jun 2013
              1. User avatar

                Doug Waldron

                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!

                17 Jun 2013
                1. User avatar

                  manthony

                  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. 

                  Regards,

                  Mary

                  17 Jun 2013
  5. User avatar

    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.

    20 Dec 2012
    1. User avatar

      Anonymous

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

      01 Jul 2013
      1. User avatar

        manthony

        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.

        02 Jul 2013
  6. User avatar

    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.

    27 Dec 2012
    1. User avatar

      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.

      30 Jan 2013
    1. User avatar

      Alexander Sideropoulos

      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.

      --ap

      22 Apr 2013
  7. User avatar

    Anonymous

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

    ex) Node.js

    28 Dec 2012
    1. User avatar

      manthony

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

      28 Dec 2012
  8. User avatar

    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`

    06 Jan 2013
    1. User avatar

      manthony

      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.

      11 Jan 2013
  9. User avatar

    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.

    12 Jan 2013
  10. User avatar

    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!

    12 Jan 2013
  11. User avatar

    Anonymous

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

    13 Jan 2013
    1. User avatar

      Breno Ribeiro

      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.

      19 Apr 2013
  12. User avatar

    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.

    15 Jan 2013
    1. User avatar

      manthony

      Put the link in a code block.

      21 Feb 2013
  13. User avatar

    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.

    19 Jan 2013
  14. User avatar

    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.

    10 Feb 2013
  15. User avatar

    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)

    18 Feb 2013
  16. User avatar

    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.

    21 Feb 2013
    1. User avatar

      manthony

      You can do this:

      ```
      #!javascript


      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.
      21 Feb 2013
      1. User avatar

        Anonymous

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

        Do I need to specify a language?

        21 Feb 2013
        1. User avatar

          manthony

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

          05 Mar 2013
  17. User avatar

    Anonymous

    How can I use tables?

    22 Feb 2013
    1. User avatar

      manthony

      Sadly, the core Markdown doesn't support tables.

      05 Mar 2013
    1. User avatar

      Doug Waldron

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

      17 Jun 2013
    1. User avatar

      Anonymous

      | Tables | Are | Cool |
      | ------------- |:-------------:| -----:|
      | col 3 is | right-aligned | $1600 |
      | col 2 is | centered | $12 |
      | zebra stripes | are neat | $1 |
      21 Jun 2013
  18. User avatar

    Anonymous

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

    26 Feb 2013
    1. User avatar

      manthony

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

      05 Mar 2013
  19. User avatar

    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)

    06 Mar 2013
    1. User avatar

      manthony

      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. 

      06 Mar 2013
  20. User avatar

    Corey Skiffington

    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.

    30 Mar 2013
    1. User avatar

      manthony

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

      01 Apr 2013
      1. User avatar

        Corey Skiffington

        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.

        01 Apr 2013
        1. User avatar

          manthony

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

          19 Apr 2013
  21. User avatar

    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

    03 Apr 2013
    1. User avatar

      Tomáš Horáček

      +1 for striked text

      12 Apr 2013
    1. User avatar

      Anonymous

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

      14 Apr 2013
    1. User avatar

      manthony

      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 thishttps://github.com/waylan/Python-Markdown

      19 Apr 2013
      1. User avatar

        Gordon McShane

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

        https://github.com/aleray/mdx_del_ins

        26 Jul 2013
        1. User avatar

          manthony

          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.

          29 Jul 2013
          1. User avatar

            Gordon McShane

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

            29 Jul 2013
            1. User avatar

              David Antliff

              For reference, strikethrough has been added using `~~text~~`.

              Refer https://bitbucket.org/site/master/issue/4412/support-strikethrough-in-markdown-readme#comment-7634506

               

              15 Jul 2014
  22. User avatar

    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.

    09 May 2013
  23. User avatar

    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

    07 Aug 2013
    1. User avatar

      manthony

      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?

      07 Aug 2013
      1. User avatar

        Anonymous

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

        11 Aug 2013
        1. User avatar

          manthony

          I used the editor toolbar and it worked for me: 

          Are you hand coding these or using the toolbar?

          12 Aug 2013
    1. User avatar

      Anonymous

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

      11 Aug 2013
      1. User avatar

        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. 

         

        22 Aug 2013
    1. User avatar

      Benjamim Sonntag

      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?)

      02 Dec 2013
  24. User avatar

    Stephen Paulsen

    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"?

    03 Oct 2013
    1. User avatar

      manthony

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

      Object
      Syntax
      Example
      pull request
      pull request #PR_NUMBER
      pull request #29
      issues
      issue #ISSUE_NUMBER
      issue #3

      commit

      7-40 chars

       

      HEX_CHARS
      bb21047
      03 Oct 2013
    1. User avatar

      Hoang Tran

      seem like no way to do that (sad)

      15 May 2014
  25. User avatar

    manthony

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

    16 Oct 2013
  26. User avatar

    Alex Wei [Atlassian]

    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.

    17 Oct 2013
    1. User avatar

      manthony

      Hi Alex! Broken link. Should be quicker now.

      17 Oct 2013
  27. User avatar

    Jan Meier

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

    16 Nov 2013
    1. User avatar

      manthony

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

      17 Nov 2013
  28. User avatar

    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.

    03 Jan 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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.

      04 Jan 2014
      1. User avatar

        Lance Lovette

        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.

        12 Feb 2014
  29. User avatar

    Anonymous

    VDO not available.

    30 Jan 2014
  30. User avatar

    Anonymous

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

    11 Feb 2014
    1. User avatar

      Jon Haynes

      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.

       

       

      04 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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!

      04 Jul 2014
  31. User avatar

    Anonymous

    The video tutorial doesn't exist anymore.

    01 Mar 2014
  32. User avatar

    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.

    16 Mar 2014
  33. User avatar

    Omar Crea

    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?

    28 May 2015
  34. User avatar

    Thomas Due

    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 README.md. 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? 

    02 Aug 2015
Powered by Confluence and Scroll Viewport