[GH-ISSUE #138] Add rule for ordered list indentation (ol-indent)

kerem commented

2026-03-07 20:03:11 +03:00

Owner

Originally created by @gandalfsaxe on GitHub (Jul 22, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/138

From the discussion in #137 we seemed to agree that a rule for ordered list indentation (alias: ol-indent) is oddly missing. Rule MD007 sets a default spaces to 2 for ordered sublists, however there is no such constraint on unordered sublists.

So while current we would only get a warning to the first (unordered) list:

* one
* two
* three
    * sub1
    * sub2

1. one
2. two
3. three
    1. sub1
    2. sub2

this issue suggests that ol-indent would also gives warning for the second (ordered) list for using 4 spaces, whereas the correct would be 3.

Originally created by @gandalfsaxe on GitHub (Jul 22, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/138 From the discussion in #137 we seemed to agree that a rule for ordered list indentation (alias: `ol-indent`) is oddly missing. Rule [MD007](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md007) sets a default spaces to 2 for ordered sublists, however there is no such constraint on unordered sublists. So while current we would only get a warning to the first (unordered) list: ```markdown * one * two * three * sub1 * sub2 1. one 2. two 3. three 1. sub1 2. sub2 ``` this issue suggests that `ol-indent` would also gives warning for the second (ordered) list for using 4 spaces, whereas the correct would be 3.

kerem added the

new rule

label

2026-03-07 20:03:11 +03:00

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@TheJaredWilcurt commented on GitHub (Aug 25, 2019):

Would this also handle this case?

1. Text

    ![This should be flagged for starting with 4 spaces instead of 2](file.png)

1. Test

@TheJaredWilcurt commented on GitHub (Aug 25, 2019): Would this also handle this case? ```md 1. Text ![This should be flagged for starting with 4 spaces instead of 2](file.png) 1. Test ```

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@jthomerson commented on GitHub (Dec 29, 2019):

Any update on this rule? If a PR were created that mimicked the behavior of ul-indent, but worked with ol's, would that be reviewed and accepted?

@jthomerson commented on GitHub (Dec 29, 2019): Any update on this rule? If a PR were created that mimicked the behavior of ul-indent, but worked with ol's, would that be reviewed and accepted?

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 29, 2019):

I have no objections to this proposed rule, but have not gotten around to adding it myself. An implementation that is structured like MD007 but applies to ordered lists seems like it would be suitable here. I’d be happy to review such a PR according to the contribution guidelines.

@DavidAnson commented on GitHub (Dec 29, 2019): I have no objections to this proposed rule, but have not gotten around to adding it myself. An implementation that is structured like MD007 but applies to ordered lists seems like it would be suitable here. I’d be happy to review such a PR according to the [contribution guidelines](https://github.com/DavidAnson/markdownlint/blob/master/CONTRIBUTING.md).

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@mschoettle commented on GitHub (Mar 16, 2025):

Would it make sense to have a generic indentation rule?

For example:

* A ul item

  ```python
  print('Hello World')
  ```

Does not render the code block indented with the ul item. Maybe it depends on the renderer though.
In any case, it could be helpful to enforce general consistent indentation.

@mschoettle commented on GitHub (Mar 16, 2025): Would it make sense to have a generic indentation rule? For example: ````markdown * A ul item ```python print('Hello World') ``` ```` Does not render the code block indented with the ul item. Maybe it depends on the renderer though. In any case, it could be helpful to enforce general consistent indentation.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 16, 2025):

FYI, the example immediately above should/does render the code fence as part of the list item (per CommonMark spec): https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20A%20ul%20item%0A%0A%20%20%60%60%60python%0A%20%20print('Hello%20World')%0A%20%20%60%60%60%0A%0A%20%20Still%20item%0A%0ANew%20paragraph%0A%0A%60%60%60python%0Aprint('Hello%20World')%0A%60%60%60%0A

@DavidAnson commented on GitHub (Mar 16, 2025): FYI, the example immediately above should/does render the code fence as part of the list item (per CommonMark spec): https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20A%20ul%20item%0A%0A%20%20%60%60%60python%0A%20%20print('Hello%20World')%0A%20%20%60%60%60%0A%0A%20%20Still%20item%0A%0ANew%20paragraph%0A%0A%60%60%60python%0Aprint('Hello%20World')%0A%60%60%60%0A

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@mschoettle commented on GitHub (Mar 17, 2025):

Indeed. I use mkdocs which uses python-markdown. Based on the documentation one difference is that it enforces the indentation to 4: https://python-markdown.github.io/#differences:

The syntax rules clearly state that when a list item consists of multiple paragraphs, “each subsequent paragraph in a list item must be indented by either 4 spaces or one tab” (emphasis added). However, many implementations do not enforce this rule and allow less than 4 spaces of indentation. The implementers of Python-Markdown consider it a bug to not enforce this rule.

This applies to any block level elements nested in a list, including paragraphs, sub-lists, blockquotes, code blocks, etc. They must always be indented by at least four spaces (or one tab) for each level of nesting.

Are you open to adding a general indentation rule instead of adding ol-indent (or both)?

@mschoettle commented on GitHub (Mar 17, 2025): Indeed. I use `mkdocs` which uses `python-markdown`. Based on the documentation one difference is that it enforces the indentation to 4: https://python-markdown.github.io/#differences: > The [syntax rules](https://daringfireball.net/projects/markdown/syntax#list) clearly state that when a list item consists of multiple paragraphs, “each subsequent paragraph in a list item must be indented by either 4 spaces or one tab” (emphasis added). However, many implementations do not enforce this rule and allow less than 4 spaces of indentation. The implementers of Python-Markdown consider it a bug to not enforce this rule. > > This applies to any block level elements nested in a list, including paragraphs, sub-lists, blockquotes, code blocks, etc. They must always be indented by at least four spaces (or one tab) for each level of nesting. Are you open to adding a general indentation rule instead of adding `ol-indent` (or both)?

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 17, 2025):

If one wants to start list item content at column 5, that is valid and supported by CommonMark: https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20%20%20List%20item%20starting%20at%20column%205%0A%0A%20%20%20%20%60%60%60python%0A%20%20%20%20print('Hello%20World')%0A%20%20%20%20%60%60%60%0A

Your configuration is starting to sound like Prettier's 4-space tab width which is discussed more here: https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/Prettier.md#list-item-indentation

I'm not sure what a "general indentation" rule would be as the choice is not always flexible (ex: code fences at 4).

@DavidAnson commented on GitHub (Mar 17, 2025): If one wants to start list item content at column 5, that is valid and supported by CommonMark: https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20%20%20List%20item%20starting%20at%20column%205%0A%0A%20%20%20%20%60%60%60python%0A%20%20%20%20print('Hello%20World')%0A%20%20%20%20%60%60%60%0A Your configuration is starting to sound like Prettier's 4-space tab width which is discussed more here: https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/Prettier.md#list-item-indentation I'm not sure what a "general indentation" rule would be as the choice is not always flexible (ex: code fences at 4).

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@mschoettle commented on GitHub (Mar 19, 2025):

Indeed. Setting ul-indent to 4 works for the list item, however, the "content" of the list item itself is not ensured to be at 4 as well. Similarly, for ul-indent: 2, if additional content is (incorrectly) indented at 1 space instead there is no violation (for ul-indent: 4 1-3 spaces cause that same behaviour).

https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20list%20item%0A%20%20spanning%20text%0A%20%20over%20multiple%20lines%0A%0A%20%60%60%60python%0A%20print('Hello%20World')%0A%20%60%60%60%0A%0A%20another%20sentence%20part%20of%20the%20first%20list%20item%0A%0A*%20list%20item%202%0A%0A%20%20sentence%0A%0ANew%20paragraph.%0A

I realize now that that has nothing to do with "general indentation" :)

Since it is not relevant to this issue I can open a new one to discuss it there.

@mschoettle commented on GitHub (Mar 19, 2025): Indeed. Setting `ul-indent` to 4 works for the list item, however, the "content" of the list item itself is not ensured to be at 4 as well. Similarly, for ul-indent: 2, if additional content is (incorrectly) indented at 1 space instead there is no violation (for `ul-indent: 4` 1-3 spaces cause that same behaviour). https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A*%20list%20item%0A%20%20spanning%20text%0A%20%20over%20multiple%20lines%0A%0A%20%60%60%60python%0A%20print('Hello%20World')%0A%20%60%60%60%0A%0A%20another%20sentence%20part%20of%20the%20first%20list%20item%0A%0A*%20list%20item%202%0A%0A%20%20sentence%0A%0ANew%20paragraph.%0A I realize now that that has nothing to do with "general indentation" :) Since it is not relevant to this issue I can open a new one to discuss it there.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 19, 2025):

Okay. FYI that I recently had a somewhat related discussion and the second half of the messages in this issue is relevant: https://github.com/DavidAnson/markdownlint/issues/1473

Specifically, I didn't see an easy way to get list item indent from the parser. However in your case, I wouldn't even be able to trust the parser because you want to pick up on cases where TOO FEW spaces are used and the list ends early. That would push the implementation over toward regular expressions which is both a blessing and a curse. :)

@DavidAnson commented on GitHub (Mar 19, 2025): Okay. FYI that I recently had a somewhat related discussion and the second half of the messages in this issue is relevant: https://github.com/DavidAnson/markdownlint/issues/1473 Specifically, I didn't see an easy way to get list item indent from the parser. However in your case, I wouldn't even be able to trust the parser because you want to pick up on cases where TOO FEW spaces are used and the list ends early. That would push the implementation over toward regular expressions which is both a blessing and a curse. :)

kerem referenced this issue

2026-03-07 20:14:56 +03:00

[PR #1964] [MERGED] Update test repository snapshots. #3677

Rows
Columns

[GH-ISSUE #138] Add rule for ordered list indentation (ol-indent) #1964