[GH-ISSUE #340] MD029 doesn't allow for start="" in ol tags

kerem commented

2026-03-03 01:25:28 +03:00

Owner

Originally created by @af4jm on GitHub (Oct 15, 2020).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/340

if I set MD029 to "ordered", I would expect any list item to get flagged if it's not 1 more than the previous number, but if I do something like...

# heading

## subheading 1

1. blah
2. blah
3. blah

## subheading 2

4. blah
5. blah
6. blah

this is "ordered", e.g. the 5. should NOT be flagged because the previous is 4... yet it is flagged and the hover text says that the setting is "1-2-3"... um, no, it's not "ordered starting with 1" it's just "ordered"... and it renders correct & valid html with start="4" on the second ol tag (I will admit this type of list only makes sense when the items in the list are naturally numbered anyway... e.g the 10 Commandments, where the subheadings would be "God" & "neighbors")

but it seems odd that markdownlint has no way of creating a start attribute without it being flagged as a violation

Originally created by @af4jm on GitHub (Oct 15, 2020). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/340 if I set MD029 to "ordered", I would expect any list item to get flagged if it's not 1 more than the previous number, but if I do something like... ``` markdown # heading ## subheading 1 1. blah 2. blah 3. blah ## subheading 2 4. blah 5. blah 6. blah ``` this is "ordered", e.g. the 5. should NOT be flagged because the previous is 4... yet it is flagged and the hover text says that the setting is "1-2-3"... um, no, it's not "ordered starting with 1" it's just "ordered"... and it renders correct & valid html with start="4" on the second ol tag (I will admit this type of list only makes sense when the items in the list are naturally numbered anyway... e.g the 10 Commandments, where the subheadings would be "God" & "neighbors") but it seems odd that markdownlint has no way of creating a start attribute without it being flagged as a violation

kerem

2026-03-03 01:25:28 +03:00

closed this issue
added the
enhancement
label

kerem commented

2026-03-03 01:25:29 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 15, 2020):

The pattern you show is not common and therefore usually represents an error, I think. The rules recommendation is consistent with the common case and by flagging each line, it means that automatic fix will be able to correct each of the list item markers. in a single pass.

It should be possible to add an additional parameter to this rule that allows starting with an arbitrary number, but it would complicate the code and I'm not sure how many people would use it.

@DavidAnson commented on GitHub (Oct 15, 2020): The pattern you show is not common and therefore usually represents an error, I think. The rules recommendation is consistent with the common case and by flagging each line, it means that automatic fix will be able to correct each of the list item markers. in a single pass. It should be possible to add an additional parameter to this rule that allows starting with an arbitrary number, but it would complicate the code and I'm not sure how many people would use it.

kerem commented

2026-03-03 01:25:29 +03:00

Author

Owner

@af4jm commented on GitHub (Oct 16, 2020):

Hmm... that's an interesting perspective... I see only 3 options...

first item can be any number, subsequent numbers increase by 1
first item can be anything, subsequent items match
linter suggests a change that alters the output (by claiming that a start attribute in an ol tag is an error)

in my opinion #3 smells like a bug, although the simple fact that this project has been around for a while working the way it is indicates I'm probably very much in the minority, so I'm going to turn this into a question...

if I were going to write a custom rule to work the way I want it to work, what would my filter look like to get all the lists? I tried to start with a copy of MD029, but it uses cache.js which probably isn't accessible from a custom rule (at least not the instance that's actually populated with the document tree). I also tried grabbing ol tags, but I think I also need the child li tags as well.
Looking through the other example rules linked didn't help, presumably because what I'm trying to do is very uncommon.

Thanks!

@af4jm commented on GitHub (Oct 16, 2020): Hmm... that's an interesting perspective... I see only 3 options... 1. first item can be any number, subsequent numbers increase by 1 2. first item can be anything, subsequent items match 3. linter suggests a change that alters the output (by claiming that a start attribute in an ol tag is an error) in my opinion #3 smells like a bug, although the simple fact that this project has been around for a while working the way it is indicates I'm probably very much in the minority, so I'm going to turn this into a question... if I were going to write a custom rule to work the way I want it to work, what would my filter look like to get all the lists? I tried to start with a copy of MD029, but it uses cache.js which probably isn't accessible from a custom rule (at least not the instance that's actually populated with the document tree). I also tried grabbing ol tags, but I think I also need the child li tags as well. Looking through the other example rules linked didn't help, presumably because what I'm trying to do is very uncommon. Thanks!

kerem commented

2026-03-03 01:25:29 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 16, 2020):

I'd suggest starting from - or modelling - MD029. cache.js is not needed - the helpers in https://www.npmjs.com/package/markdownlint-rule-helpers should help with some of the grunt work. You can see what the parse tree looks like for different syntax by looking at the "debug" tab on https://markdown-it.github.io/.

I'll caution you that your item 1 would allow "2/3/4" which is usually wrong and item 2 would allow "5/5/5" which is probably also wrong. You may want to remember previous lists and allow starting with a number other than 1 iff the previous list ended with the previous value.

Good luck!

@DavidAnson commented on GitHub (Oct 16, 2020): I'd suggest starting from - or modelling - MD029. `cache.js` is not needed - the helpers in https://www.npmjs.com/package/markdownlint-rule-helpers should help with some of the grunt work. You can see what the parse tree looks like for different syntax by looking at the "debug" tab on https://markdown-it.github.io/. I'll caution you that your item 1 would allow "2/3/4" which is usually wrong and item 2 would allow "5/5/5" which is probably also wrong. You may want to remember previous lists and allow starting with a number other than 1 iff the previous list ended with the previous value. Good luck!

kerem commented

2026-03-03 01:25:29 +03:00

Author

Owner

@af4jm commented on GitHub (Oct 16, 2020):

Thanks... and point taken on your "usually wrong" comments, which 100% counter my arguments above... so far I have a custom rule doing exactly what MD029 does out of the box, once I get it doing the custom thing (not today, but probably this weekend) I'll stick it in a gist & link to it here for future reference... but I have definitely been swayed that the existing behavior of MD029 is what makes sense for most cases

@af4jm commented on GitHub (Oct 16, 2020): Thanks... and point taken on your "usually wrong" comments, which 100% counter my arguments above... so far I have a custom rule doing exactly what MD029 does out of the box, once I get it doing the custom thing (not today, but probably this weekend) I'll stick it in a gist & link to it here for future reference... but I have definitely been swayed that the existing behavior of MD029 is what makes sense for most cases

kerem commented

2026-03-03 01:25:30 +03:00

Author

Owner

@nschonni commented on GitHub (Oct 16, 2020):

@af4jm unless this style is all over your docs, it might be easier to just use <--markdownlint-disable MD029--> and <--markdownlint-enable MD029--> comments around specific blocks you're sure about

@nschonni commented on GitHub (Oct 16, 2020): @af4jm unless this style is all over your docs, it might be easier to just use `<--markdownlint-disable MD029-->` and `<--markdownlint-enable MD029-->` comments around specific blocks you're sure about

kerem commented

2026-03-03 01:25:30 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 16, 2020):

@af4jm Feel free to publish your rule to npm. If you tag it (see CustomRules.md), others can find it.

@DavidAnson commented on GitHub (Oct 16, 2020): @af4jm Feel free to publish your rule to npm. If you tag it (see CustomRules.md), others can find it.

kerem commented

2026-03-03 01:25:30 +03:00

Author

Owner

@af4jm commented on GitHub (Oct 17, 2020):

published, thanks!

@nschonni I didn't want to do that because the repo in question is an Azure DevOps wiki I'm using to replace my Evernote account (partly because it's the only Markdown-based wiki I could find... and being free was just a bonus.)

@af4jm commented on GitHub (Oct 17, 2020): published, thanks! @nschonni I didn't want to do that because the repo in question is an Azure DevOps wiki I'm using to replace my Evernote account (partly because it's the only Markdown-based wiki I could find... and being free was just a bonus.)

kerem commented

2026-03-03 01:25:30 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 17, 2020):

Congrats! I'll leave this issue open to consider enhancing MD029 with an option to allow list continuations.

@DavidAnson commented on GitHub (Oct 17, 2020): Congrats! I'll leave this issue open to consider enhancing MD029 with an option to allow list continuations.

kerem commented

2026-03-03 01:25:30 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 19, 2021):

Closing this based on it usually being an error - and because there's now a rule to help with this: https://www.npmjs.com/package/markdownlint-rule-olstart.

@DavidAnson commented on GitHub (Jun 19, 2021): Closing this based on it usually being an error - and because there's now a rule to help with this: https://www.npmjs.com/package/markdownlint-rule-olstart.

kerem referenced this issue

2026-03-07 20:04:31 +03:00

[GH-ISSUE #292] trailing spaces not allowed in code block #2095

Rows
Columns

[GH-ISSUE #340] MD029 doesn't allow for start="" in ol tags #292