Nested numbered list indentation differs from bullet lists

Summary

Writing Markdown lists differs between bullets and numbered lists:

Steps to reproduce

The result of the following Markdown would produce unexpected results:

# Bullets

* this is parent
  * this is child 1
  * this is child 2

# Numbered (expected)

1. this is parent
  1. this is child 1
  1. this is child 2

# Numbered (current status)

1. this is parent
    1. this is child 1
    1. this is child 2

Example Project

This bullet list worked, but this numbered one didn't.

What is the current bug behavior?

The following does not result the same as if there were bullets:

 1. this is parent
   1. this is child 1
   1. this is child 2

What is the expected correct behavior?

The previous layout should be indented and formatted correctly, as the following one:

* this is parent
  * this is child 1
  * this is child 2

mentioned in issue #34645 (closed)

mentioned in issue #34741 (closed)

mentioned in issue #34835 (closed)

mentioned in issue #34964 (closed)

@agiammarchi per the screenshot of the link you provided, what is it exactly that you feel is incorrect about the indentation? It seems that the words have the same indentation ...

If you would add some annotated screenshots, that might help. Thanks!

Chrome:

Firefox:

added Category:Wiki awaiting feedback devopscreate markdown severity4 typebug + 1 deleted label

see that? that's what didn't work, and following the raw version of that page:

Raw link here https://gitlab.com/eyeo/adblockplus/abpui/wiki/raw/07162343191757a5284512fd7229bc194fa4f066/res/issues-guideline.md

mentioned in issue #35037 (closed)

Thanks @agiammarchi! That helps a lot!

added severity3 label and removed awaiting feedback severity4 labels

@andr3 , is this a frontend issue?

mentioned in issue #35490 (closed)

mentioned in issue #35984 (closed)

mentioned in issue #36575 (closed)

mentioned in issue #37190 (closed)

mentioned in issue #37868 (closed)

mentioned in issue #39010 (closed)

mentioned in issue #103411 (closed)

mentioned in issue #121489 (closed)

mentioned in issue #193035 (closed)

added frontend label

mentioned in issue #195107 (closed)

mentioned in issue #196471 (closed)

mentioned in issue #197805 (closed)

changed milestone to %Backlog

added priority4 label

added priority3 label and removed priority4 label

changed weight to 1

As it looks the bug is further about numbered lists not properly being indented at all resulting in wrong results. Definitely something we should address

@cdybenko as we tackle quite some Wiki work in the next cycle afaik, this could potentially fit right in. I added the %Backlog milestone for now.

@rkuba thanks for sourcing this. Seems like an easy win to include

added [deprecated] Accepting merge requests label

changed milestone to %12.9

changed milestone to %12.10

added missed:12.9 label

changed milestone to %13.0

added missed:12.10 label

added workflowready for development label

@rkuba this missed 2 milestones because it didn't have the workflow labels so it didn't make it on the board. I'll be more mindful of that moving forward! Just added it for %13.1

changed milestone to %13.1

added Stretch label

@tomquirk if you have a few down times this release and need a change to Figma, it would be nice if you could pick this up

assigned to @tomquirk

mentioned in issue create-stage#12630 (closed)

removed [deprecated] Accepting merge requests label

After some investigation, I am not sure whether this is a ~bug, and even so, it does not apply only to Category:Wiki but all markdown-enabled parts of GitLab. In my observation, the behavior of Markdown on GitLab Wikis can be replicated in other Markdown renderers (including in other areas of GitLab, e.g. Issue discussions like this one).

Here are some examples from VSCode:

Parent (2-space indent) and Child (4-space indent)

This is the case reported as a bug in this issue (notably, the parent has indentation):

And in this very comment, this raw Markdown:

  1. Parent
    1. Child

renders as:

1. Parent 1. Child

Parent (0-space indent) and Child (4-space indent)

Parent (0-space indent) and Child (2-space indent)

Parent (2-space indent) and Child (6-space indent)

@cdybenko @rkuba let me know how you would like to proceed, and please let me know if I have overlooked something critical here.

@tomquirk thanks for the investigation. That is a good question. @cdybenko it seems like it's working as expected if there is a 4 space indentation between levels. So probably a documentation issue? Wdyt?

@rkuba I think we are ok to just update the docs with this. Is this on us or @marcia?

I'm not sure that this should be documented for/in GitLab, although I'd definitely appreciate @marcia's opinion. Given that GitLab extends the CommonMark spec (from the source file, and using the commonmarker library) and this issue isn't specific to our implementation, it seems like this would be best documented elsewhere.

For reference, I dived a little deeper into this to clarify . Tl;dr: GitLab's implementation does appear to conform with the CommonMark spec.

---

From the CommonMark spec section 5.2:

If a sequence of lines Ls constitute a sequence of blocks Bs starting with a non-whitespace character, and M is a list marker of width W followed by 1 ≤ N ≤ 4 spaces, then the result of prepending M and the following spaces to the first line of Ls, and indenting subsequent lines of Ls by W + N spaces, is a list item with Bs as its contents.

Consider the test case reported in this issue:

  1. Parent
    1. Child

So, in this case:

• W = 4 (2 spaces preceding the list marker + 2 character list marker ('1.'.length = 2)
• N = 1 (1 space follows the list marker)

∴ Subsequent lines should be list items if they are intended by 4 + 1 = 5 spaces

In this test case, the child element is only indented by 4 spaces, and is therefore not considered part of the list. The "expected" result is achieved with 5 spaces.

Please correct any of the above if there is a mistake!

@cdybenko @agiammarchi we use two different markdown engines, one for GitLab, the app (CommonMark), and another for the docs site (GitLab Kramdown). Therefore, they cannot be directly compared.

If the problem is in GL's markdown fields and markdown rendering, this doesn't have anything to do with docs, it would be a GL frontend issue. If we need a fix to the text displayed on docs.gitlab.com, that would be a docs project's frontend issue. ;) Apparently, from what I understood, we need a fix in both. Is this correct?

@marcia I honestly don't know the difference or implementation details, but this page is not showing what it should. Is that a doc's project? To us, that is an .md file in our wiki. Sorry for probably not helping much in here, but as FE "consumer", I wouldn't know what's doing what behind the MD to HTML scene.

Oh, thanks, Andrea. Maybe I misunderstood the whole thing. It seems that it works, it's just not properly documented, is that it?

Marcia, if I write this:

1. this is parent
2. this is child 1
3. this is child 2

you should see 1, within nested 1 and 2 .. if that's not the case, it's a bug to me, as the equivalent in bullets, would work

• this is parent
  • this is child 1
  • this is child 2

above should be one black filled outer bullet, and two white filled one.

Marcia, this is a copy and paste of what I've written in there:

Marcia, if I write this:

1. this is parent
  1. this is child 1
  1. this is child 2

you should see 1, within nested 1 and 2 .. if that's not the case, it's a bug to me, as the equivalent in bullets, would work

* this is parent
  * this is child 1
  * this is child 2

above should be one black filled outer bullet, and two white filled one.

Marcia ... OK, this looks fine:

1. this is parent
   1. this is child 1
   2. this is child 2

• this is parent
  • this is child 1
  • this is child 2

written as:

1. this is parent
   1. this is child 1
   1. this is child 2

* this is parent
  * this is child 1
  * this is child 2

I guess if there's a standard behind this behavior, as I can counter validate in other places it's the same, then it's definitively a documentation gotcha, but practically, for a user, these are the steps:

### this works
* star space line
  * space space star space indented

### this doesn't
1. number dot space line
  1. space space number dot space NOT indented

I think this is a bug, not a feature, but I'd understand if you want to keep it aligned with other implementations.

In such case, feel free to close this.

@agiammarchi I think you nailed it in #34572 (comment 358997927)!

To echo what you've already said, my interpretation of the CommonMark spec leads me to believe that:

This will result in nesting:

1. this is parent
   1. this is child 1
   1. this is child 2

This will not result in nesting:

1. this is parent
  1. this is child 1
  1. this is child 2

There does appear to be an intentional difference between numbered and bulleted lists; because their "widths" are different ('1.'.length = 2, and '*'.length = 1), CommonMark wants an additional space of indentation for nested numbered lists compared to bulleted lists (see my comment #34572 (comment 358395807) for reference to the spec).

So, I am going to close this, but just to let you know that the person that invented markdown didn't mean to need extra spaces on the numbered list, as you can test here, so this CommonMark specification/implementation seems to break the initial purpose of markdown itself: be simple, be readable, just work.

I know this is not a big deal, but it's surely a surprise that visually, while you type MD, doesn't make sense, it's just an implementation decision, which is also not standardized across parsers.

Closing this, as I guess you want to stick with CommonMark.

Thanks for having a look though, at least I've learned something

@agiammarchi glad to help! It was interesting to get to the bottom of this . Thank you for raising the issue.

FWIW, I have no opinion on whether CommonMark is the best implementation and tend to agree with you that is a surprise (especially when other parsers behave differently, including the DaringFireball example) - I was just trying to understand why GitLab (and CommonMark) behaves this way. If this issue surfaces again elsewhere, I will remember this discussion and refer back to it!

closed

added groupeditor [DEPRECATED] label and removed 1 deleted label

added Category:Markdown label

added sectiondev label