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

Create a `max-heading-level` rule

Open iansan5653 opened this issue 2 years ago • 2 comments

When Markdown content is rendered on GitHub, it is rendered into the context of a webpage. This means there is already an external heading structure to contend with.

In issue and PR comments, the maximum heading level that should be used is 3 (###). In files in Code View, the maximum should be 2 (##).

I think it's debatable whether Markdown files should be written with their intended viewing location in mind - Markdown is supposed to be a rendering-agnostic markup format. But comments should probably always be written like this. So I think it would be useful to make a new rule available, but disable it by default.

I propose we make this generic, allowing the linter to customize the heading level for the situation. For example, the following configuration would be for comments on github.com:

{
    "max-heading-level": {
        "level": 3
    }
}

Related:

  • https://github.com/iansan5653/github-markdown-a11y-extension/issues/14

iansan5653 avatar Oct 06 '23 15:10 iansan5653

I think this is an interesting rule to provide, and I agree it should be disabled by default. Consumers might also want to singularly import this rule even if they're not using the full accessibility set.

I might propose using the naming of start-heading-level rather than use max or min, but that's purely an ergonomic consideration.

andrialexandrou avatar Oct 09 '23 21:10 andrialexandrou

If we do decide to add this rule here, I've written it in github-markdown-a11y-extension as start-heading-level - we can definitely copy/paste it.

iansan5653 avatar Feb 22 '24 13:02 iansan5653