[FIXED] How to prevent Markdown's list from eating spaces?

Issue

I have:

- `foo`: some text                       Default: false
- `barThatIsTooLong`: again some text    Default: true

but in Bitbucket README, whitespaces will be eaten automatically, and this will be displayed as:

• foo: some text Default: false
• barThatIsTooLong: again some text Default: true

I would like to have the default values vertically aligned.

How to tell Bitbucket's markdown to not eat my spaces? Is it even possible?

Solution

You probably can't, unless you use tables instead of lists.

| Variable           | Description     | Default |
| -------------------|---------------- | ------- |
| `foo`              | some text       | false   |
| `barThatIsTooLong` | again some text | true    |

If you are using a site which doesn't strip out raw HTML and/or style attributes, then inline floats might work:

- `foo`: some text                    <span style="float:right; width:10em;">Default: false</span>
- `barThatIsTooLong`: again some text <span style="float:right; width:10em;">Default: true</span>

The long answer

Collapsing whitespace is a "feature" of HTML, of which Markdown is a subset. The "feature" is often referred to as "insignificant whitespace." The idea is that all whitespace (spaces, tabs, newlines, etc.) is collapsed into a single space (see a summary of whitespace behavior options). Note that this collapse of whitespace is being done by your browser, not the Markdown parser. If you use your browser's "view source" of "inspect" feature, you will see that the HTML list retains the whitespace:

<ul>
<li><code>foo</code>: some text                       Default: false</li>
<li><code>barThatIsTooLong</code>: again some text    Default: true</li>
</ul>

In other words, Markdown is not eating your whitespace, your browser is. So the next question is how to preserve whitespace in HTML and how that can be incorporated into your Markdown. There are a number of different ways to do that, but, in the end, they will not work as you desire.

1. The <pre> tag preserves whitespace, but is a block-level tag and not for inline use. As you only want some inline whitespace, preserved, not the entire block of text, this is not useful.

2. The whitespace:pre CSS rule could be used to get that effect, but will look ugly in your Markdown. Also, Bitbucket may strip your style tags for security reasons (SO does).

   - `foo`: some text<span style="white-space:pre">                       </span>Default: false
   - `barThatIsTooLong`: again some text<span style="white-space:pre">    </span>Default: true
   

3. As non-breaking spaces are not collapsed, you could use them rather than regular spaces. In fact, you only need every other space to be a non-breaking space. But, again, it is ugly. Even worse, as non-breaking spaces are entered as HTML entities, one displayed character is 6 characters long in your Markdown, so the columns don't line up properly in the source document.

   - `foo`: some text                       Default: false
   - `barThatIsTooLong`: again some text    Default: true
   

But even if you get one of the above to work, the browser probably still won't display your list as you desire. Bitbucket, like most websites do not use monospace fonts for their website (except in code blocks). Therefore, the width of each letter in a line is not equal and your columns still won't line up. Notice that the same situation exists here on SO. The last example above renders like this:

• foo: some text                       Default: false
• barThatIsTooLong: again some text    Default: true

You can see the same effect in your editor. If you change the font from a monospace font to a proportional font you will notice that the columns will misalign. And that misalignment will vary with each different proportional font. Therefore, simply adjusting the number of spaces won't guarantee proper alignment. You may even end up with a half-width misalignment.

Of course, websites have columns all the time. But those columns are not "faked" with inline text. Each column is wrapped in its own block-level element and CSS rules position and size the containing box appropriately as demonstrated in this answer. But again, that requires raw HTML and CSS which Bitbucket is likely to not allow for security reasons.

One other option might be to use inline floats:

- `foo`: some text                    <span style="float:right; width:10em;">Default: false</span>
- `barThatIsTooLong`: again some text <span style="float:right; width:10em;">Default: true</span>

This causes the <span> to be floated to the far right edge of the containing block (the list item). To avoid the floated items appearing right aligned, we have included the width which ensures that each <span> is the same width. The actual width needs to be at least as wide as the largest text within the span. However, there is still the fact that Bitbucket will likely strip out the raw HTML for security reasons.

However, Bitbucket's Markdown implementation does support simple tables. So if you really want columns, you could implement them as tables. Of course, you would need to have table rows rather than list items in addition to column headers, which you may or may not want.

| Variable           | Description     | Default |
| -------------------|---------------- | ------- |
| `foo`              | some text       | false   |
| `barThatIsTooLong` | again some text | true    |

Answered By - Waylan

Answer Checked By - Marilyn (PHPFixing Volunteer)