Markdown rendering
Asked by Mohit Tendolkar:

Hi, I have markdown text that includes cases like newlines specified by a "\<br/\>", or special characters like "\<" indicated as "\\\<" so that the rendering takes on the behavior specified by these directives and characters. This worked just fine in previous versions of GIT (or tools like MS VisualCode markdown editor). However when viewing the MD files hosted in Bitbucket via a Chrome browser, the rendering now reveals all these cases and the document is no longer formatted as expected. Could someone please help me so that I can get consistent rendering of the markdown text across older versions of GIT and BitBucket? Thanks


Answers:
author: Caroline R
body: Hi, [@Mohit Tendolkar](/t5/user/viewprofilepage/user-id/4494474)! Welcome to the community!

Currently, Bitbucket doesn't support arbitrary HTML in Markdown, for example \<table\> tags. Instead, we use safe mode. The safe mode requires that you replace, remove, or escape HTML tags appropriately.

However, we already have an open feature request to Support some or all HTML in Markdown:

* <https://jira.atlassian.com/browse/BCLOUD-6930>

I've linked your question to these features. Please consider adding yourself as a watcher, this way you get updated as we make progress with this.

If you are not familiar with our Feature Request Policy, you can read more about it here:

* [Implementation of New Features Policy](https://confluence.atlassian.com/support/implementation-of-new-features-policy-201294576.html)

Also, I would suggest you access our [Markdown tutorial](https://bitbucket.org/tutorials/markdowndemo/src) if you would like to read more about Bitbucket Supported Markdown.

I hope this helps, but please let me know if you have any questions.

Kind regards,  
Caroline

comments: author: Mohit Tendolkar
body: Hi Caroline,

Appreciate the prompt reply!

I understand not supporting arbitrary HTML tags and that's perfectly OK.

The reason I had to resort to HTML tags such as \<br/\> (line break) was it appeared to be the recommended and most widely used scheme to explicitly insert line breaks in mark down content when grepped on the Internet. Furthermore, the associated rendering works just fine with earlier versions of GIT and other third party Markdown editors.

Could you please confirm that the Bitbucket policy of not supporting "arbitrary" HTML tags deviates from classic/legacy GIT markdown support?

Could you please suggest Bitbucket compliant alternatives for the following:

\* Insertion of explicit line breaks in regular paragraphs. For example, I want the next para to begin three lines after the current para ends.

\* Insertion of explicit line breaks for bulleted items for a column in a table row. For example I want to document the possible/legit values of a variable (the variable properties are columnized as a row in a table). For that one column I would like each value to appear on a separate line (hence line break)

\* Allow rendering of text surrounded by angle brackets. For example I want text such as \<some text\> to be rendered. In classic markdown, the angle bracket had to be preceded with an escape character like "\\\<". However now with Bitbucket, the rendering exposes the escape character.

Thus note that I am not seeking support for "arbitrary" HTML in Markdown, I'm merely seeking compatibility with existing GIT and general Markdown schemes that appear to be in deployed use.

Please do let me know

Thanks

Mohit


author: Caroline R
body: Hi, Mohit!

Allow me to reply to each of your questions directly and feel free to share any further questions or concerns about the information I will share with you.
> Could you please confirm that the Bitbucket policy of not supporting "arbitrary" HTML tags deviates from classic/legacy GIT markdown support?

I confirmed with our engineers that, due to a series of security concerns, they disabled HTML markdown rendering.
> Insertion of explicit line breaks in regular paragraphs. For example, I want the next para to begin three lines after the current para ends.

You can use \&nbsp; between the lines to insert line breaks in regular paragraphs:

```
line1&nbsp;&nbsp;&nbsp;line2
```

> Insertion of explicit line breaks for bulleted items for a column in a table row. For example I want to document the possible/legit values of a variable (the variable properties are columnized as a row in a table). For that one column I would like each value to appear on a separate line (hence line break)

Bitbucket does not support \`\<html\>\` so you need to use the - (dash) and the \| (pipe) symbols to construct a table. The first line contains column headers. Separate columns with the pipe symbol.

The second line must be a mandatory separator line between the headers and the content. Subsequent lines are table rows. Columns are always separated by the pipe (\|) character. For example this table:

```
First Header  | Second Header------------- | -------------Content Cell  | Content CellContent Cell  | Content Cell
```

> Allow rendering of text surrounded by angle brackets. For example, I want text such as \<some text\> to be rendered. In classic markdown, the angle bracket had to be preceded with an escape character like "\\\<". However now with Bitbucket, the rendering exposes the escape character.

You don't need to add a \\\<some text\>, you can simply add \<some text\> and it should work:

![Screen Shot 2021-08-06 at 12.23.51 PM.png](https://community.atlassian.com/t5/image/serverpage/image-id/154973i62E2593EA94A1907/image-size/large?v=v2&px=999 "Screen Shot 2021-08-06 at 12.23.51 PM.png")

I hope this helps, but please let me know if you face any obstacles.

Kind regards,  
Caroline


Tags: bitbucket-cloud

cloud