markdownlint-github icon indicating copy to clipboard operation
markdownlint-github copied to clipboard

Provide rationale for the rules enabled or disabled

Open khiga8 opened this issue 3 years ago • 2 comments

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.

khiga8 avatar Dec 22 '22 17:12 khiga8

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.

chris-c-thomas avatar Feb 06 '23 16:02 chris-c-thomas

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

andrialexandrou avatar Oct 09 '23 21:10 andrialexandrou