Was just bitten by this today. Documentation is conflicting:
The markdowndemo repository states that you do not support HTML and use "safe mode", linking to a documentation page that has been down since January 2018. Relatedly, an archive of the linked page from a month after that section was last updated (February 2015) explicitly says that safe_mode is deprecated and should not be used. The current documentation for the python-markdown library that is the target of the broken link explains that safe_mode is deprecated and recommends bleach-allowlist as a replacement that still allows a subset of HTML.
The bottom of the Markdown Syntax Guide says you implement the Common Mark spec and says explicitly at the bottom that the file can contain "a restricted set of HTML tags" without specifying what. See this community post from 2018 for confusion around that guide.
This community post from 2017 states that we can use HTML tags and again links to the Common Markdown spec, which states the following:
Text between < and > that looks like an HTML tag is parsed as a raw HTML tag and will be rendered in HTML without escaping. Tag and attribute names are not limited to current HTML tags, so custom tags (and even, say, DocBook tags) may be used.
And further, earlier comments on this issue make mention of a Labs feature that supposedly supported HTML in Markdown as late as 2019, but I see no such Labs option in my account today.
For better or for worse, a core feature of Markdown is that it falls back to HTML, and many repositories have leveraged that to create richer READMEs. Bitbucket not supporting this is a notable deficit compared to competitors, and makes working with repositories originally hosted elsewhere rather unpleasant.
Please, give us at least an allowed subset of HTML to work with here.
Hi everyone,
Thank you for your patience. The Bitbucket Cloud team has successfully shipped this feature to our customers! Attached are some screenshots of what this will look like. We are going to go ahead and close out this BCLOUD ticket, but please feel free to continue adding questions, comments, or any other feedback here.
Best,
Luke