markdownlint-github
markdownlint-github copied to clipboard
Provide rationale for the rules enabled or disabled
I think it will be helpful to provide context on why we recommend these configurations.
In base.json
{
"default": true,
"no-inline-html": false,
"no-bare-urls": false,
"no-blanks-blockquote": false,
"fenced-code-language": true
}
In accessibility.json
{
"no-alt-text": true,
"no-default-alt-text": true,
"no-duplicate-header": true,
"no-emphasis-as-header": true,
"no-generic-link-text": true,
"no-space-in-links": false,
"ol-prefix": "ordered",
"single-h1": true,
"ul-style": true
}
Some of these are somewhat obvious, while others are less so.
I think a doc page of some sort would definitely be great. I love opinionated things but also want to know the reasoning behind other's choices before I adopt it.
Adding a note here to emphasize how some of the accessibility rules here are indeed related to accessibility, for instance
- ul style asterisk
- no space in links being disabled
- ol prefix ordered