Bitbucket nested lists

[gautaz]

Hello,

Looking at the Bitbucket's Markdown syntax guide where Markdown should be written "as specified in CommonMark (with a few extensions)", the following example of a nested ordered list is given:

1.  Step 1
2.  Step 2
3.  Step 3
    1.  Step 3.1
    2.  Step 3.2
    3.  Step 3.3

This example shows that Bitbucket expects the list content to be indented with 4 spaces.
This seems to comply with the rule number 3 detailed in the section 5.2.1 (Motivation) of the CommonMark specification:

“List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab.”

This example is rendered as expected on Bitbucket but remark-lint will report errors like:

warning Unexpected `2` spaces between list item marker and content, expected `1` space, remove `1` space list-item-indent          remark-lint

Fixing these errors gives the following Markdown content:

1. Step 1
2. Step 2
3. Step 3
   1. Step 3.1
   2. Step 3.2
   3. Step 3.3

But doing this will cripple the Bitbucket HTML rendering which will display all the list elements at the same level, i.e.:

<ol>
<li>Step 1</li>
<li>Step 2</li>
<li>Step 3</li>
<li>Step 3.1</li>
<li>Step 3.2</li>
<li>Step 3.3</li>
</ol>

Is this the expected behavior?
Is the Bitbucket interpretation of CommonMark valid?
Is there a way to configure remark-lint rules so that they comply with Bitbucket's interpretation of CommonMark?

[ChristianMurphy]

BitBucket is not implementing commonmark
Here is your example in commonmark's reference parser.
https://spec.commonmark.org/dingus/?text=1.%20Step%201%0A2.%20Step%202%0A3.%20Step%203%0A%20%20%201.%20Step%203.1%0A%20%20%202.%20Step%203.2%0A%20%20%203.%20Step%203.3

[gautaz]

Hello @ChristianMurphy, thank you for your answer.

Still, I'm not sure how to interpret this as I can put both versions in the commonmark's reference parser, it doesn't seem to complain on either of them and renders the exact same result in both cases. Here is the result for the "Bitbucket version":

https://spec.commonmark.org/dingus/?text=1.%20%20Step%201%0A2.%20%20Step%202%0A3.%20%20Step%203%0A%20%20%20%201.%20%20Step%203.1%0A%20%20%20%202.%20%20Step%203.2%0A%20%20%20%203.%20%20Step%203.3

So how does this rule out the "Bitbutcket version"?
Which specific part of the Commonmark specification does this "Bitbucker version" not comply about?
What about this rule number 3 detailed in the section 5.2.1 (Motivation) of the CommonMark specification saying:

“List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab.”

[ChristianMurphy]

TL;DR

• Both of your snippets are valid CommonMark.
  In CommonMark, the space after a list marker can be 1-4. The indentation required for any following lines (including sublists) is W + N, where W is the width of the marker (e.g., 1. → 2 chars) and N is the spaces after it.

  “M is a list marker of width W followed by 1 ≤ N ≤ 4 spaces of indentation … indenting subsequent lines … by W + N spaces.”
  (CommonMark section 5.2 “List items”, rule 1)

  That’s why both:

  1. Step 1
  2. Step 2
  3. Step 3
     1. Step 3.1
     2. Step 3.2
     3. Step 3.3
  

  (N = 1 → continuation/subcontent indent must be W+N = 3)

  and

  1.  Step 1
  2.  Step 2
  3.  Step 3
      1.  Step 3.1
      2.  Step 3.2
      3.  Step 3.3
  

  (N = 2 → continuation/subcontent indent must be W+N = 4)

  are parsed the same by a CommonMark-conforming parser.

• Bitbucket requiring exactly 4 spaces for nesting is not CommonMark; it follows the older “four-space rule” that CommonMark explicitly moves away from in favor of the relative W + N model:

  “The strategy here is to let the width and indentation of the list marker determine the indentation necessary for blocks to fall under the list item, rather than having a fixed and arbitrary number.”
  (CommonMark section 5.2.1 “Motivation”)

  And, specifically for sublists:

  “The rules for sublists follow from the general rules above. A sublist must be indented the same number of spaces of indentation a paragraph would need to be included in the list item.”
  (CommonMark section 5.3 “Lists”)

---

Answers to your questions

1. Is this the expected behavior?

   • CommonMark: Yes; both versions should nest correctly.
   • Bitbucket: Their renderer flattening the one-space version is expected for Bitbucket, but it is not CommonMark behavior.

2. Is Bitbucket’s interpretation valid CommonMark?

   • No. Enforcing a fixed 4-space indent for nesting conflicts with section 5.2 (rule 1’s W + N) and the sublist rule in section 5.3.

3. Can remark-lint be configured to comply with Bitbucket’s rendering?

   • The list-item-indent warning is a style rule, not a correctness rule. CommonMark allows 1–4 spaces after the marker; Bitbucket prefers 2 + nested 4. If Bitbucket is your target renderer, you can:
     • Disable the rule locally around affected snippets:

       <!--lint disable list-item-indent-->
       1.  Step 1
       2.  Step 2
       3.  Step 3
           1.  Step 3.1
       <!--lint enable list-item-indent-->

     • Or turn off / relax list-item-indent in your .remarkrc so that two spaces after the marker (and 4-space nesting) pass lint.

If you have the option, I recommend sticking with CommonMark-compliant formatting (single space after markers; indent subcontent by W + 1) for portability across parsers. If you are bound to Bitbucket’s renderer, standardize on “two spaces after the marker + 4 spaces for nested content” and adjust lint accordingly.

[gautaz]

Thanks a lot @ChristianMurphy!
That makes more sense now, I was under the impression that the 4 spaces were a requirement but the "W + N" rule feels in fact more sensible.
Have a nice day!