Support some or all HTML in Markdown (BB-6931)

Issue #6930 open
Former user created an issue

Markdown doc says embedded HTML should work; it doesn't. This would be a huge workaround to the inordinate number of missing features in Markdown.

Official response

  • Brian Edwards staff

    If you look on the "Bitbucket Labs" page, you will see a new Beta feature named "Embedded HTML in markdown". Be aware that it switches to a completely new markdown rendering backend. You will get support for some embedded HTML tags, but you might need to rework your markdown files to handle differences with the two rendering packages. Most notably the new one is more strict in requiring a blank line after headers.

Comments (167)

  1. Christopher Keele

    While there is no Markdown spec, inline HTML is supported by most markdown implementations. Notably, Github. Comparisons will be made.

    I bring this up because no markdown implementation supports some kind of anchor construct outside of hyperlinks. This makes it impossible to link to particular segments of a README or add a nice internally linked table of contents without adding your own raw HTML anchor tags. My READMEs kind of fell apart after migrating to Bitbucket, because it doesn't support raw tags.

    Daring Fireball mentions this feature pretty explicitly. It's not exactly a spec, but it's the main implementation documentation for the language.

  2. Thomas Neirynck

    I agree with the above:

    "My READMEs kind of fell apart after migrating to Bitbucket, because it doesn't support raw tags"

    I had the same thing happening after migrating from github. Support for this would be a nice improvement.

  3. Thomas Neirynck


    maybe this relates more to #6322 which is only about the anchor links. But that was closed as duplicate of this one.

    The headers in the HTML generated from the markdown get an id-property.

    Bitbucket seems to prepend "markdown-header" to the text of the header, strip all special characters (./#), transform to lower case, and replace whitespace with a dash.

    So as a work-around, I hardcode these IDs as my anchor links

    e.g. my markdown looks like this.

    The forward anchor link

    1. **[Link to Header](#markdown-header-1-header)**: some 

    Somewhere else in the document, the actual anchor.

    ##  1. Header

    The header tag in the generated html looks something like this.

    <h2 id="markdown-header-1-header">1. Header</h2>

    The anchor link will work correctly. It's hacky I know - and presumable only works because of bitbucket's particular html-generator, but at least it gets the anchor links working. It's probably not the most robust forward-compatible solution though.

  4. Gordon Leigh

    Is there any reason not to support inline HTML? Markdown is a pretty limited format without it... I too am mainly interested in anchor support for tables of contents.

  5. Jan-Eric Duden

    Daring Fireball explicitly says in the Spec:

    For any markup that is not covered by Markdown’s syntax, 
    you simply use HTML itself. 
    There’s no need to preface it or delimit it to indicate 
    that you’re switching from Markdown to HTML; 
    you just use the tags.

    Even if you decide not to include the feature, it would be good to have the differences documented somewhere.

  6. Former user Account Deleted

    For folks trying to create a table of contents note that putting [TOC] in the document will do this automatically. This doesn't eliminate the desirability of embedded HTML (e.g. for better list control) but it does solve one important use case.

  7. Jesper Öqvist

    It would be great if embedded HTML could be supported by bitbucket. It would be very useful together with the Wiki feature. How can we make Atlassian change their mind on this?

  8. Kirill Muzykov

    Not sure this is a duplicate. First of all duplicate issue is about supporting "small subset" of HTML and "strike" tag in particular, and this issue has a wider scope. Secondly, this issue has bigger amount of votes. I would reverse duplicate relationship between those 2 issues.

  9. Gabriel Schubiner

    I agree, @Kirill Muzykov

    Also, as a note on only supporting a subset of HTML tags, I use emacs org-mode for my documentation, which can export to markdown, but assumes a full set of HTML tags are available. It would be incredibly helpful to have the full set of tags available, since this is the assumption in general, and it would make bitbucket compatible with any number of tools that can export to markdown.

  10. Christopher Keele

    I'd concur with @Kirill Muzykov. The markdown spec encourages full access to HTML; obviously this is a tall order if you're compiling other peoples' arbitrary markdown the way Bitbucket is. There has to be a blacklist/whitelist. On the other hand, it's not clear which tags people on this issue want supported, but it's a lot more than <strike>.

    Perhaps we can start to list the tags we'd like to have access to, so that they have a starting point? I, for one, would love full access to the anchor element, with internal linking, and all tags I'm likely to embed inside a link (as markdown won't process markdown inside raw HTML).

    Alternatively, what's a reasonable blacklist of HTML elements?

  11. Gabriel Schubiner

    I'm not sure why there has to be a blacklist.. I understand it may not be an insignificant amount of work to implement, but there could be an option to use a library like PageDown for rendering.

    I don't want to be presumptuous, since I don't know how bitbucket's backend for rendering markdown currently works, but they are already rendering the markdown to html. just leave the HTML in markdown files alone, and send it to the browser to render. it undoubtedly takes more than just that to integrate HTML in the current rendering engine, but i can't imagine there isn't a generic solution to recognizing and embedding html.

    The only tags I can think that should be blacklisted are <script> and other tags that bring security concerns.

  12. Christopher Case

    BitBucket (as mentioned in #4412) uses Python Markdown for it's markdown rendering. Looking at the documentation, (specifically about safe_mode) the authors comment:

    See Also: HTML sanitizers (like Bleach) may provide a better solution for dealing with markdown text submitted by untrusted users. That way, both the HTML generated by Markdown and user submited raw HTML are fully sanitized.

    There's no reason to have the community whitelist/blacklist tags, when a library (recommended by the authors of the currently used markdown library) exists to do exactly what we want.

  13. Christopher Case

    Do the developers have any feelings about solutions such as Bleach? I would assume it would need to go through some sort of security audit before it would be able to be used; though what I'm more interested in knowing, I guess, is if a sanitization solution like that would meet security requirements, or if instead only a whitelist like solution is the only acceptable route.

    As a side note, I completely understand the tradeoffs that need to be made with regards to security. Frankly, I'm just excited this issue is getting attention. (And, I'll completely accept a whitelist if that's what's mandated.) It would just be nice to know the context to have a useful discussion within.

  14. Bogdan Vatulya

    I wanted to add an embedded youtube video / a video tag to a video in a bitbucket repository (simple how-to video). But without inline html support it is not possible in markdown.

  15. Theodore Brown

    I have copyright symbols in my READMEs (&copy;), and it really annoys me that they appear literally, rather than as the intended symbol the way other markdown parsers display them.

  16. MikeS

    I tried adding <nobr> and <br> within table cells where I was displaying CSS classes, and they just wrapg it very ugly and, and difficult to read. Ugh!

  17. Ændrew Rininsland

    Strike. Please, add strike. In Atlassian world, people who file issues may be smart enough to create separate issues, but us in the real world frequently have to deal with folks who try to cram a list of 10 points into a single issue, and short of taking half an hour to separate all those out into separate issues, using strikeout is the best way of depicting which points have been addressed.

    tl;dr -- not having strike imposes a somewhat-serious usability issue for some users.

  18. Paul Rupe

    <pre>, <code> tags with the ability to use formatting like <b>, <i>, etc. within them.

    Say I have /path1/path2/path3/path4/file.ext maybe by itself or as part of a larger code block, and I want to emphasize the path4/file.ext part. I don't see any way to do this with the existing wiki languages.


  19. Christopher Case

    Honestly, I don't see a sane way to do that. What if you're writing C code?

    char **foobar;

    How is the wiki syntax supposed to differentiate between an un-closed bold syntax, or a pointer to a pointer? Using the html tags makes it even worse; you can never put html code in a code block if you do that.

    Honestly, I'll just be happy with strikeout.

  20. Christopher Keele

    @prupe Markdown has never supported extra emphasis tags inside code blocks. If you think about it, that's entirely counterintuitive to the purpose of <pre>.

    This issue isn't about inventing a new markup syntax. It's also not asking Bitbucket to support a single new tag, such as <strike>. It's about the existing markdown parser, which fails to comply with a well-defined spec where all of these considerations are already addressed:

    For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

    The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces.

    - Daring Fireball

  21. Alexander Lukanin

    I agree with @prupe, it would be nice to allow HTML <pre><code> with embedded <b> and <i>. Sometimes you need to provide an example of working in shell and highlight user input. With indented code block it's not possible by design, so using <pre> is the only option.

  22. Patrick Mentz

    I am using inline svg in my markdown… well I was using it, as it seems now. :> What I like is the principle of some markdown processor to allow the author to use any kind of html within a <div> or <span> tag. If you fear the security risks, maybe it's an option to allow it at least for private repositories.

  23. Mr Roberts

    Our team is attempting to use our repo wikis to detail UI interactions more explicitly and having some HTML support to enable this would be a huge help.

  24. Adrien Tétar

    Bitbucket, you are violating the gist of Markdown by not supporting this &ndash; Markdown is not a subset of HTML, it is HTML with syntax sugar for common notation patterns.

    You won't compete with GitHub if you don't resolve issues like this.

  25. Ændrew Rininsland

    The glacial pace at which Atlassian is working to resolve this is more than a little bit unsettling... The new ~~ and ++ symbols should be removed and HTML allowed. That's really all there is to it. I now regret advocating for something as simple as strikeout earlier on, didn't realise it would create such a completely-ignored regressive issue...

  26. Patrick O'Keeffe

    Please, please, please, just disable 'safe_mode' and use a proper tool like bleach for HTML sanitation like the author of Python-Markdown suggests. I can understand the need to sanitize but the inability to add simple entities like copyright and trademark symbols is baffling to a lot of users. Some might go so far as to say the situation is "stupid."

    Alternatively, switch to a superior version of markdown, like Github-Flavored-Markdown. Sure, it's Github, yeah yeah, but it is a superior variant.

  27. Michael Lippert

    I understand the need to sanitize the html for security reasons, but I see other comments (such as that from @Patrick O'Keeffe) on how to do that.

    Personally I got here when I found I couldn't use write 10<sup>n</sup> and H<sub>2</sub>O. (the 1st is real the 2nd is an example.

  28. Pat Sissons

    I was a bit shocked to find out that my <br/>'s were not being rendered as actual line breaks. Even more shocked to find out that it is actually not possible to insert line breaks into a table. The funny thing here is that a white list would take any normal dev team, even for a massive project like bitbucket, only a few weeks at most to implement. Years later, everyone still scratching their heads on how various simple HTML markups are not supported.

  29. Christopher Keele

    When this issue was created, I don't think that CommonMark was a thing, yet. If I were re-evaluating the Markdown parsing of any major project today, I'd embrace it as the most future-proof, inter-operable choice of technology. There's a Python implementation, and as a plus it eliminates the burden of maintenance and questions of feature-support from the organization using it by deferring to a community standard.

  30. Timm Wagener

    Just signed up with bitbucket for the nice opportunity to have private repos. I also imported all my public repos from github, but all my carefully crafted README files definitely fell apart big time, since i totally rely on HTML in there. I feel like a beautifull README is the inviting entry point to your repo and therefore not totally unimportant at least for public repos. HTML often means the difference between only neutral and informative (without) and designed and inviting (with). Would be great to see it enabled here.

  31. DevilsJin


    how i got here

    I find it ridiculous not being able to color the fonts in my documentation. In my opinion this should be somewhat a key feature since colors are the best way to highlight parts and drawing the readers attention (if for eg. someone wanted to note a bug/issue which is realy important to read).

    The not so adequate markdown is a major reason for me to switch back to GitHub since in my opinion wikis and documentations are realy important, especially for open-source projects. Can't work without it anymore.

  32. Yu-Jie Lin

    I am also looking forward to <kbd> support like @Alexandre Alves de Sá, though I don't usually write in Markdown but reStructuredText.

    I want to bring up an issue on GitHub, which has been supporting the tag in reST for nearly three months. Hopefully, this would give the staff another reason to implement something, even the issue was about reST.

    @ Bitbucket staff

    Frankly, I don't think the staff should mark other issues which specifically request certain tags unless someone is maintaining a list of tags here. For now, it's very ambiguous about what tags are in request and messy about the rationales users brought to the staff.

    This issue is flooded with many comments, which could have been left to those issues rather than all mixed up here. I myself only care about <kbd> even I don't write in Markdown, <br> and <pre> ain't needed in reST. And I am expected to receive comments, which I don't care to read, after I comment.

    So, wouldn't it be better to leave those issues open?

  33. Thanos Psaridis

    The problem is that my IDE (intellij/android studio) eliminates all the extra spaces at the end of each line so a <br> tag would be more handy. But I don't thing what you're saying is valid anywas stylig

  34. Joe Adams

    Bump! Trying to get <sup>superscript</sup> to work so I can use the Wikipedia-style <sup>[n]</sup> references, allowing such a tag would be much appreciated :)

  35. Rutger Storm

    This is a major annoyance since all the other markdown supporting now support HTML tags or at least the most common subset. But staff will probably stay silent on this issue too like most others.

  36. Joshua Perry

    I find myself on this page often, copying and pasting a unicode pipe doppleganger while trying to document parameters, using industry standard notation, in table cells on the wiki linked to, yes, a source code repository.

  37. Benjamin Echols Account Deactivated

    We're working on improvements to our Markdown handling that will allow use of more HTML elements. Early testing has revealed some performance impacts, so we're working out those kinks. I hope to have more to share soon!

  38. Tom Roche

    Thanks for CommonMark support. Has anyone got links to good doc about it? CM has a detailed spec (to which I have linked from Wikipedia), but I'd appreciate something that focuses on the differences between CM and "old-school BB Markdown." From this issue and the latest CM spec, I'm guessing the main difference is raw HTML, but I'm also guessing BB is not gonna support all/any HTML--am I missing something?

  39. peeter tomberg

    @Brian Edwards How would I go about actually enabling it? Does it work out of the box with the *.md extension? Cause I enabled it on our work account and see no changes thus far.

    I'm mostly interested in not showing HTML comments, e.g.

  40. Brian Edwards staff

    Install the add-on and choose "CommonMark" instead of the default file-viewer for *.md files. You are correct that it currently doesn't render HTML, but we may add support in the future.

  41. Jesper Öqvist

    @Brian Edwards I figured out how to enable "CommonMark", but it did not solve my problems:

    • I mostly care about the Overview page for my repository - switching default file viewer does not seem to affect that.
    • I want others who visit my repository to see HTML entities like &Ouml; rendered correctly - because otherwise my name is not rendered correctly. Switching my default file viewer does not seem to affect other users.

    Please please please consider adding HTML entities support (&Ouml;, etc.) to the Bitbucket Overview page. It's the most portable way to get non-ASCII characters I know of and most Markdown implementations support it well.

    As an aside, CommonMark seems to dramatically increase page loading/rendering time when viewing Markdown files.

    For anyone else wondering how to switch to using CommonMark: this helped me (see the first image).

  42. Beta


    In the wiki, I want to put a list of twig filters inside a table and can't use | even inside ``, and neither will the HTML entity for it.

  43. Vlad Spears

    Upvote. I want double line breaks, so perhaps support for <br> will get me there. If there's already a way to do this, I haven't been able to find it.

    I should be able to use two lines with two spaces in each to get a double line break. Bitbucket collapses these to a single line break, which isn't even part of the Markdown spec.

  44. Kashif Khan

    Also really wish this was supported. Most of our product documentation is written in HTML and then compiled into appropriate docs leaving me with either not using markdown or somehow integrating it via inline includes which is not supported by bitbucket :(

    Another would be to re-write all our docs in markdown and then reverse inject into html at build but that would suck even more as we then have to convert each project :(

    so yah.. till then no markdown in our projects :(

  45. Sam Blåsvær

    So, this thread has been going on since what early 2013 – ! Four and a half year …

    And we still haven't got the slightest support for HTML!? Is this due to arrogance or lack of skills, or <insert reason>?

  46. Former user Account Deleted

    After denying it for four and a half year, I imagine there'd be an element of shame if they suddenly changed their mind.

  47. Kashif Khan

    @Sam Blåsvær

    Thats my issue.. our docs, etc are in pdf, chm and htm/l.. being able to somehow incorp into would be ideal with htm/l linkage support or injecting i would need very little changes to workflows.

    I suppose injecting html opens the door to security issues with java script but they could disable that.

    So i'm left with either writing a custom chm/html to markdown which sucks as it adds to another thing to maintain or live without using markdown :(

  48. Brooklyn Foundry

    This is embarrassing -- my mirrored repos, from Github and Gitlab, all include README's with T.O.C links. It looks absolutely horrendous on Bitbucket and I feel sorry for any user having to interact with it from your web UI.

    It's 2017.

  49. Mark Edgington

    At this point, it's quite clear that the BB team is no longer paying any attention to this bug (or, for example, Issue #6569), so perhaps a new strategy is in order.

    Don't waste your time adding new "+1"s to this report, but rather let's find out who works at BB that can influence a decision on this, and make efforts to contact her/him. If anyone has any contact info of such people, pass it along so we can directly ask them about it.

    On the other hand, unless you're forced to use BB for work, maybe it's better to advocate against it and just choose an alternative service for now.

  50. Hajime Yamasaki

    This issue is almost 5 years old now. There are several logical conclusions:

    • The BitBucket team doesn't really care
    • The BitBucket team doesn't read issues
    • The BitBucket team doesn't know how to implement this
    • They know how to implement it, but there is some religious reason why they won't

    In GitHub, this feature works fine.

    GitLab has a nice workaround in some cases.

    My impression is that the level of attention to detail tips the scale in favor of competing services, and that it's a waste of time to bump this issue any further.

  51. Fernando Torres

    Well, it is amazing that this issue is going on since 2013 ... so no real hope to have a well rendered .md ...

    Anyways, my concern is to format image files ... so usually I insert <img> tags instead of the native markdown style to have more control ... but it doesn't render here ...

    Vote for the issue!

  52. Claire Bianchi Account Deactivated

    We are currently gathering feedback as we roll out the new Atlassian editor and have not made a determination on this feature.

    Please continue to follow this ticket for updates, and add comments describing any use-cases that are important to your team and not already covered above.

    Thanks, Claire

  53. Florian Friedrich

    We use our README also in the docs that are generated by jazzy. We have tables in our README and we add some custom css classes to them inside jazzy. To do that, we can't use markdown tables (even if they were supported by bitbucket), because we need to add our classes. While GitHub and GitLab can easily deal with inline HTML, it looks crappy in bitbucket.

    Also as mentioned by others, the markdown spec explicitly mentions inline html.

  54. tgaff

    @cbianchi2 How much more feedback on this issue could you need? Surely the team can see how long this has been annoying users, how many monthly views this gets and emails are sent; plus the same for the related issues the team marked as duplicates (e.g. )

    I only clicked on the email this time so I could unfollow 6322 because I'm tired of getting emails for an issue that obviously will not be fixed. I have given up on anything happening here. After 5 years, how many other users might be in that bucket? How many other users like me have decided not to try other Atlassian products as a result?

  55. Martin Dvorak

    @cbianchi2 I also vote for fixing no inline HTML support as it's de facto standard violation. My use cases range from rendering of HTML comments to anchor links.

    I can give you a number of very popular Markdown documents whose rendering on BB is just disaster. Their authors go with your competitors, because they simply cannot use BB as rendered Markdowns are not readable. This is where you lose users and customers.

  56. Sean Kauffman

    I just want a way to escape a | character in a table. That is all I ask! An HTML entity is the normal way you would solve this without support for backslash escapes (which is also a standard md thing since 2017, I believe). The lack of HTML support in general is extremely annoying.

  57. Former user Account Deleted

    Ok, so I no longer use BB, so you can safely ignore my comment if it annoys you. And I guess I'm going to be a bit obnoxious.

    The last feedback from the staff was that:

    We are currently gathering feedback

    If you scroll up from that point and look at older messages, you will see that many issues have already been marked as duplicates of this issue. There's been a fair deal of feedback here, and a fair deal of feedback in the duplicates. We are entering the sixth year since this issue was first identified. The person managing this project should step down.

  58. Mario Biberhofer

    Neither org-files, nor markdown or html exports are working in bitbucket.

    As long as at least this feature is not implemented, this product has a big no-go sticker at it from my company's perspective. Even small systems like gitea support this, it's a joke that no one attends to this feature for 5+ years.

  59. Brian Espinosa

    I think @Hajime Yamasaki nailed it with this one:

    They know how to implement it, but there is some religious reason why they won't

    At this point it is beyond ridiculous that this has not yet been implemented. Especially considering that this feature is simply hidden behind a configuration variable. I know that Atlassian has invested a lot of time in improving the UI recently but honestly... who cares about the UI improvements if they are at the expense of the user experience?! I have had to disable almost all of the new UI displays because they are either half baked and still seem very much in beta, or they removed a key piece of functionality.

    Here's another related issue also opened back in 2013 to support task lists in markdown:

    These are not requests for massive, innovative features. They are minor requests to bring Bitbucket into feature parity with competitors with features that they have been missing for years. Stop screwing the user, Atlassian.

  60. Brian Edwards staff

    If you look on the "Bitbucket Labs" page, you will see a new Beta feature named "Embedded HTML in markdown". Be aware that it switches to a completely new markdown rendering backend. You will get support for some embedded HTML tags, but you might need to rework your markdown files to handle differences with the two rendering packages. Most notably the new one is more strict in requiring a blank line after headers.

  61. Victor Sluiter

    I tried this. First: thanks for implementing it, at least it's an acknowledgement to all the people asking for this feature. Second: please also support HTML entities , I'm using a lot of &mu;seconds , which should read as microseconds, or M&Omega; which should read as megaohm.... I can now finally use superscript and subscript using HTML, but the subset of this feature is too limited at this moment....

  62. Victor Sluiter

    Hi Brian,

    This is not a functional fix for me. Within the <p></p> tags I cannot use markdown, and using something like **please** see<p>&sect;</p> for more details will (understandably) create a new paragraph with just the section name. The p tags are not a solution, it should work without that, as HTML entities are already standard since HTLML3.2, and can be used by other Markdown implementations without problems (I'm using VSCode with Markdown Preview Enhanced as editor for markdown, Mkdocs for documentation, Pandoc with reveal.js for presentations). Please confer to the standard so that I can re-use documentation without worrying about the platform.

    <small>I'd even suggest to go a step further and add the LateX rendering between $ signs.... </small>

  63. Victor Sluiter

    Another issue: I can't use syntax highlighting in the new version. Normally I use ```xml or ```c to start highlighting the code as XML or C (or JavaScript, or Matlab, or....) . That used to work, but seems to be broken in the new implementation. I'm switching back to the old markdown version.

  64. Victor Sluiter
    • changed status to closed
      This is fixed with the Bitbucket Labs feature titled "Embedded HTML in markdown".

    I doubt that. Not even considering the implementation problems with syntax highlighting and HTML entities, the feature is now enabled per-person. I cannot use HTML and be sure that my team sees what I'm seeing. I think this issue should only be closed when the feature has made it to the default workflow.

  65. Hajime Yamasaki

    I think this issue should only be closed when the feature has made it to the default workflow.

    Hey, don't discourage them. It's a step in the right direction nevertheless. After 6 long years, almost. ;)

  66. Sean Kauffman

    I agree with Victor that this should not be closed. In my case I just want to be able to display a pipe "|" in a table. I still can't do this with the labs feature. Maybe we should all just make separate tickets for exactly the markup we want to use.

  67. Paulius Pupeikis

    I've seen some opinions that BB cannot change markdown syntax to keep backward compatibility. Good point but that would leave us all stuck in 2013 forever. My humble suggestion is to have a first line of the markdown file that would indicate which markdown converter should be used. Something like:

    markdown-parser: BitBucketNewAndImproved2019

    Different or missing line would mean "classic" parser. Maybe there are better proposals but I have not seen them yet.

  68. Adam Shaylor

    Please don’t bother preserving the idiosyncrasies Bitbucket’s current Markdown compiler.

    Most Markdown editors/parsers/compilers use either something closer to John Gruber’s original Perl compiler, GFM, or CommonMark: specifically, VS Code, Atom’s markdown-preview package (which uses the marked compiler), iA Writer, and Byword. It is only after users upload documents that rendered in a manner consistent with one of those standards that we see those documents break in Bitbucket. The attempt to WYSIWYG away this problem with a live editor only makes the problem worse. Try, for example, to format text inside a link; it used to be easy, but now it’s impossible.

    I also ask that we keep this ticket open until the beta markdown compiler is no longer just an experimental feature but baked into every aspect of Bitbucket, from READMEs to pull requests.

  69. Log in to comment