Hi David,
I think proposed changes are fine. Does MD025 only checks for multiple top
level headers (as in H1s)? Or others as well? If it’s just H1s, then I would
keep it enabled. Other then that, everything else looks good.
I would personally enable most of them, problem is, it’s hard enough to get
people to write documentation as is (myself included:)) and stylistic rules
might stop somebody from submitting their pull request.
Thanks,
Ilya Volodin
P.S. I think MD033 might not work 100%. I know I’ve seen a rule documentation
somewhere in ESLint that was using <pre> instead of ``` and it wasn’t erroring.
From: [email protected] [mailto:[email protected]] On Behalf Of
David Anson
Sent: Saturday, May 16, 2015 6:39 PM
To: [email protected]
Subject: [ESLint] On finding the right balance for markdownlint rules
When it comes to linting, I tend to enable everything then back down on just
the most troublesome rules - but I appreciate that's not the right approach for
everyone. :)
The ESLint preference seems to be in favor of rules related to parser issues
(which have caused problems in the past) and against rules that are purely
stylistic.
I've reviewed the current rules and will send a pull request to disable
anything people feel isn't valuable.
Below is a list of the current state and proposed changes. See
https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md for more
details on any rule.
Currently enabled, keep enabled:
MD003 - Header style (style=consistent within file)
For this and similar stylistic issues, it seems reasonable to require a
consistent style *within the same file* (even if other files differ)
MD004 - Unordered list style (style=asterisk)
PROPOSED CHANGE: style=consistent within file
MD005 - Inconsistent indentation for list items at the same level
Possible parser issue
MD006 - Consider starting bulleted lists at the beginning of the line
Possible parser issue
MD007 - Unordered list indentation (indent=4)
Possible parser issue
MD009 - Trailing spaces
This came up as part of https://github.com/eslint/eslint/issues/2478,
but because of the 2-space behavior
(http://daringfireball.net/projects/markdown/syntax#p), I propose leaving it
enabled
MD010 - Hard tabs
Possible parser issue (ex: GitHub)
MD011 - Reversed link syntax
Incorrect syntax
MD018 - No space after hash on atx style header
Possible parser issue
MD020 - No space inside hashes on closed atx style header
Possible parser issue
MD022 - Headers should be surrounded by blank lines
Known parser issue
MD023 - Headers must start at the beginning of the line
Possible parser issue
MD027 - Multiple spaces after blockquote symbol
Possible parser issue
MD028 - Blank line inside blockquote
Possible parser issue
MD031 - Fenced code blocks should be surrounded by blank lines
Known parser issue
MD032 - Lists should be surrounded by blank lines
Known parser issue
MD033 - Inline HTML
Possible parser issue
MD035 - Horizontal rule style (style=consistent)
Consistency
MD036 - Emphasis used instead of a header
User error, known to have happened in ESLint
MD037 - Spaces inside emphasis markers
Possible parser issue
MD038 - Spaces inside code span elements
Possible parser issue
MD039 - Spaces inside link text
Possible parser issue
Currently enabled, CHANGE to disabled:
MD001 - Header levels should only increment by one level at a time
Rule is for correct HTML <h#> hierarchy
MD014 - Dollar signs used before commands without showing output
Individual preference
MD019 - Multiple spaces after hash on atx style header
Unlikely parser issue
MD021 - Multiple spaces inside hashes on closed atx style header
Unlikely parser issue
MD024 - Multiple headers with the same content
Possibly deliberate
MD025 - Multiple top level headers in the same document
HTML suggestion
MD030 - Spaces after list markers
Unlikely parser issue
MD040 - Fenced code blocks should have a language specified
Language auto-detection is generally quite good, so this usually has no
effect
Currently disabled, keep disabled (there are existing violations for all of
these):
MD002 - First header should be a h1 header
MD012 - Multiple consecutive blank lines
MD013 - Line length
MD026 - Trailing punctuation in header
MD029 - Ordered list item prefix
MD034 - Bare URL used
Please let me know what you prefer and I'll make the corresponding updates to
the config!
Also, please let me know if there are any rules you'd like to see *added* (ex:
trailing newline at end of file). I've skimmed the ESLint issue history for
ideas, but might have missed some opportunities. :)
--
You received this message because you are subscribed to the Google Groups
"ESLint" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected]
<mailto:[email protected]> .
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"ESLint" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
