[GH-ISSUE #1] Consider using key for rules instead of number #1849

New issue

Closed

opened 2026-03-07 20:02:05 +03:00 by kerem · 4 comments

kerem commented

2026-03-07 20:02:05 +03:00

Owner

Originally created by @MoOx on GitHub (Jun 12, 2015).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1

Why did you choose numbers ? Is there any references somewhere ?

Some others linters are using clear key (eg: eslint, styelint etc)

Originally created by @MoOx on GitHub (Jun 12, 2015). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1 Why did you choose numbers ? Is there any references somewhere ? Some others linters are using clear key (eg: eslint, styelint etc)

kerem

2026-03-07 20:02:05 +03:00

closed this issue
added the
enhancement
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jun 12, 2015):

Thanks for the suggestion! I'm a big fan of ESLint and like the readability rule names offer. In this case, markdownlint has its roots in a Ruby implementation and I wanted to maintain as much compatibility as possible, so I used the same MD### system for naming. (More info: http://dlaa.me/blog/post/markdownlint)

That said, I think I could support both systems (MD### for compatibility and short-rule-names for readability). I'll look into supporting this soon - or else follow up here with a reason I don't think it will work.

@DavidAnson commented on GitHub (Jun 12, 2015): Thanks for the suggestion! I'm a big fan of ESLint and like the readability rule names offer. In this case, `markdownlint` has its roots in a Ruby implementation and I wanted to maintain as much compatibility as possible, so I used the same MD### system for naming. (More info: http://dlaa.me/blog/post/markdownlint) That said, I think I could support both systems (MD### for compatibility and short-rule-names for readability). I'll look into supporting this soon - or else follow up here with a reason I don't think it will work.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 19, 2015):

I ran this by Mark and we're thinking to use something close to the following list for both JavaScript and Ruby. Both implementations will support both naming styles interchangeably. I've got an idea how I want to code this and should be able to make progress this week.

MD001 - header-indent - Header levels should only increment by one level at a time
MD002 - first-header-h1 - First header should be a h1 header
MD003 - header-style - Header style
MD004 - ul-style - Unordered list style
MD005 - list-indent - Inconsistent indentation for list items at the same level
MD006 - ul-start-left - Consider starting bulleted lists at the beginning of the line
MD007 - ul-indent - Unordered list indentation
MD009 - no-trailing-spaces - Trailing spaces
MD010 - no-hard-tabs - Hard tabs
MD011 - no-reversed-links - Reversed link syntax
MD012 - no-multiple-blanks - Multiple consecutive blank lines
MD013 - line-length - Line length
MD014 - commands-show-output - Dollar signs used before commands without showing output
MD018 - no-missing-space-atx - No space after hash on atx style header
MD019 - no-multiple-space-atx - Multiple spaces after hash on atx style header
MD020 - no-missing-space-closed-atx - No space inside hashes on closed atx style header
MD021 - no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style header
MD022 - blanks-around-headers - Headers should be surrounded by blank lines
MD023 - header-start-left - Headers must start at the beginning of the line
MD024 - no-duplicate-header - Multiple headers with the same content
MD025 - single-h1 - Multiple top level headers in the same document
MD026 - no-trailing-punctuation - Trailing punctuation in header
MD027 - no-multiple-space-blockquote - Multiple spaces after blockquote symbol
MD028 - no-blanks-blockquote - Blank line inside blockquote
MD029 - ol-prefix - Ordered list item prefix
MD030 - list-marker-space - Spaces after list markers
MD031 - blanks-around-fences - Fenced code blocks should be surrounded by blank lines
MD032 - blanks-around-lists - Lists should be surrounded by blank lines
MD033 - no-inline-html - Inline HTML
MD034 - no-bare-urls - Bare URL used
MD035 - hr-style - Horizontal rule style
MD036 - no-emphasis-as-header - Emphasis used instead of a header
MD037 - no-space-in-emphasis - Spaces inside emphasis markers
MD038 - no-space-in-code - Spaces inside code span elements
MD039 - no-space-in-links - Spaces inside link text
MD040 - fenced-code-language - Fenced code blocks should have a language specified
MD041 - first-line-h1 - First line in file should be a top level header

@DavidAnson commented on GitHub (Jul 19, 2015): I ran this by Mark and we're thinking to use something close to the following list for both JavaScript and Ruby. Both implementations will support both naming styles interchangeably. I've got an idea how I want to code this and should be able to make progress this week. MD001 - header-indent - Header levels should only increment by one level at a time MD002 - first-header-h1 - First header should be a h1 header MD003 - header-style - Header style MD004 - ul-style - Unordered list style MD005 - list-indent - Inconsistent indentation for list items at the same level MD006 - ul-start-left - Consider starting bulleted lists at the beginning of the line MD007 - ul-indent - Unordered list indentation MD009 - no-trailing-spaces - Trailing spaces MD010 - no-hard-tabs - Hard tabs MD011 - no-reversed-links - Reversed link syntax MD012 - no-multiple-blanks - Multiple consecutive blank lines MD013 - line-length - Line length MD014 - commands-show-output - Dollar signs used before commands without showing output MD018 - no-missing-space-atx - No space after hash on atx style header MD019 - no-multiple-space-atx - Multiple spaces after hash on atx style header MD020 - no-missing-space-closed-atx - No space inside hashes on closed atx style header MD021 - no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style header MD022 - blanks-around-headers - Headers should be surrounded by blank lines MD023 - header-start-left - Headers must start at the beginning of the line MD024 - no-duplicate-header - Multiple headers with the same content MD025 - single-h1 - Multiple top level headers in the same document MD026 - no-trailing-punctuation - Trailing punctuation in header MD027 - no-multiple-space-blockquote - Multiple spaces after blockquote symbol MD028 - no-blanks-blockquote - Blank line inside blockquote MD029 - ol-prefix - Ordered list item prefix MD030 - list-marker-space - Spaces after list markers MD031 - blanks-around-fences - Fenced code blocks should be surrounded by blank lines MD032 - blanks-around-lists - Lists should be surrounded by blank lines MD033 - no-inline-html - Inline HTML MD034 - no-bare-urls - Bare URL used MD035 - hr-style - Horizontal rule style MD036 - no-emphasis-as-header - Emphasis used instead of a header MD037 - no-space-in-emphasis - Spaces inside emphasis markers MD038 - no-space-in-code - Spaces inside code span elements MD039 - no-space-in-links - Spaces inside link text MD040 - fenced-code-language - Fenced code blocks should have a language specified MD041 - first-line-h1 - First line in file should be a top level header

kerem commented

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

Author

Owner

@mivok commented on GitHub (Sep 8, 2015):

So I've finally gotten around to working on implementing this (in ruby markdownlint), and took another look at the rule names. What are your thoughts on MD001 / header-indent being labeled something like header-increment or something like header-levels? The headers aren't really indented.

@mivok commented on GitHub (Sep 8, 2015): So I've finally gotten around to working on implementing this (in ruby markdownlint), and took another look at the rule names. What are your thoughts on MD001 / header-indent being labeled something like header-increment or something like header-levels? The headers aren't really indented.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 8, 2015):

Agreed, I like your proposal of header-increment better!

@DavidAnson commented on GitHub (Sep 8, 2015): Agreed, I like your proposal of `header-increment` better!

kerem referenced this issue

2026-03-07 20:09:17 +03:00

[GH-ISSUE #1849] You got it #2605