How to add newline inside table cell in Markdown in Bitbucket Wiki?

Question

How to add newline inside table cell in Markdown in Bitbucket Wiki?

<br> -- doesn't work

<br/> -- doesn't work

bullets -- doesn't work

Answer 1

If <br> or <br /> don't work, then you probably can't.

Unfortunately, Bitbucket's documentation regarding table support is rather sparse and consists solely of the following example:

| Day     | Meal    | Price |
| --------|---------|-------|
| Monday  | pasta   | $6    |
| Tuesday | chicken | $8    |

However, that syntax looks like the rather common table syntax first introduced by PHP Markdown Extra and later popularized by GitHub, MultiMarkdown, and others.

PHP Markdown Extra's rules state:

You can apply span-level formatting to the content of each cell using regular Markdown syntax:

| Function name | Description                    |
| ------------- | ------------------------------ |
| `help()`      | Display the help window.       |
| `destroy()`   | **Destroy your computer!**     |

GitHub's spec plainly states:

Block-level elements cannot be inserted in a table.

And MultiMarkdown's rules state:

Cell content must be on one line only

In fact, notice that the syntax does not offer any way to define when one row ends and another row begins (unlike the header row, which includes a line to divide it from the body of the table). As you cannot define the division between rows, then the only way it can work is if each line is its own row. For that reason, a row cannot contain multiple lines of text.

Therefore, any text within a table cell must be inline text only, which can be represented on a single line (therefore the Markdown standard of two spaces followed by a newline won't work; neither will bullets as they would be block level list elements). Of course, a raw HTML <br> tag is inline text and would qualify as a way to insert line breaks within table cells. However, some Markdown implementations disallow all raw HTML as a security measure. If you are using such an implementation (which Bitbucket appears to be using), then it is simply not possible to include a line break in a table cell.

I realize some find the above frustrating and limiting. However, it is interesting to note the following advice in MultiMarkdown's documentation regarding tables:

MultiMarkdown table support is designed to handle most tables for most people; it doesn’t cover all tables for all people. If you need complex tables you will need to create them by hand or with a tool specifically designed for your output format. At some point, however, you should consider whether a table is really the best approach if you find MultiMarkdown tables too limiting.

The interesting suggestion is to consider using something other than a table if you can't do what you want with the rather limited table syntax. However, if a table really is the right tool, then you may need to create it by hand. As a reminder, the original rules state:

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown's formatting syntax only addresses issues that can be conveyed in plain text.

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.

Therefore, creating a table by hand requires using raw HTML for the entire table. Of course, for those implementations which disallow all raw HTML you are without that option. Thus, you are back to considering either non-table solutions or a way to format a table without any line breaks within cells.