Use human readable key value pairs for configuration. about markdownlint HOT 4 CLOSED

I'm not sure how I feel about not having a numeric ID for rules, but the two arguments I have in favor of them (easier to type and refer to in chat/IM/issues, and no need to change the ID later if the name doesn't make sense any more, such as if I'd named MD007 'multimarkdown_list_indent' before discovering another reason for wanting 4 space indents) aren't that strong. The inspiration for this way of doing things btw is Foodcritic rather than rubocop. It's interesting to see the different choices made between the two.

I do really like the idea of having rules be able to take parameters in style files, and it does neatly solve the issue of multiple rules that do essentially the same thing as well as conflicts.

from markdownlint.

Parameters are done and in a branch. They'll be merged once I clean up the rules to use them.

However, regarding rule names, I think I'm still going to come down on the side of
having a short, mostly numeric, identifier for all rules. I've thought about
it quite a bit and there are two other issues I came across while trying out
named rules:

• Some of the later rules will end up with rule names almost as long as the
  descriptions in order to fully specify what they do (e.g. multiple spaces
  inside hash on atx_closed headers), and while parameters have helped with some
  of those (the header style rule description is much more concise), it won't
  help everywhere.
• Remembering the name of the rule without looking it up is more difficult than
  remembering a shorter number (e.g. was the rule name
  header_trailing_blank_line, header_surround_blank_lines or something else).

Both of these could be solved with aliases, but that sacrifices
recognizability of a given rule, especially if more terse forms are used, and
you're right back to the original issue that prompted having.

Ultimately, the tradeoff is reading and recognizing (in style files or other
places where it won't have the description printed next to the ID) vs writing
and remembering.

from markdownlint.

I understand the difficulty, and of course the final decision is up to you.

I believe:

1. When writing the config file: both numbers and meaningful names are hard enough to remember that people writing the config file will have to look up the docs in both cases for a very long time before they are confident enough with them to write the config without checking.
2. When reading:
   • for readable IDs, you might have to look a few times at the docs, but it is likely that you will soon be able to guess correctly what they mean.
   • for numbers, readers will have to look at the docs for way longer before they memorize what they mean. They could always add comments to the config file, but then why not use the comment strings as data instead of the IDs?

People will read the files much more than they write them, since every contributor has to read it to know what style to use, but only a few owners will modify the file occasionally.

from markdownlint.

The rule parameters option has been merged. As part of this, I updated the style files to not have to exclude the rules that have now been removed. As part of this, I simplified the ************ style file significantly. Let me know if the changes make sense or not.

For now I'm closing this issue. Docs on creating style files/rules/parameters I'll add as a separate issue.

from markdownlint.