For the linting error, we could just disable it. Take a look at the pull request template of Super-Linter: https://github.com/super-linter/super-linter/blob/0aa20740a5c28e959f0452846601e35a91d958c6/.github/pull_request-template.md

https://github.com/super-linter/super-linter/blob/0aa20740a5c28e959f0452846601e35a91d958c6/.github/pull_request-template.md?plain=1#L1-L10

They start with:

<!-- Start with an H2 because GitHub automatically adds the commit description before the template, -->
<!-- so contributors don't have to manually cut-paste the description after the H1. -->
<!-- Also, include the header in a "prettier ignore" block because it adds a blank line -->
<!-- after the markdownlint-disable-next-line directive, making it useless. -->
<!-- Ref: https://github.com/prettier/prettier/issues/14350 -->
<!-- Ref: https://github.com/prettier/prettier/issues/10128 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable-next-line MD041 -->
## Readiness checklist
<!-- prettier-ignore-end -->

In order to have this pull request merged, complete the following tasks.

This is very distracting in a PR template. Can this be disable in a configuration file for this specific file.

I think the H1 warning makes sense for most files, but not here, and having another disable to make the first disable work just adds to the confusion here.

Partially off-topic, but relevant: Now when I think about this, for Markdown documentation, we also expect to start with H2 just like we do in HTML because the file is a stub, not a complete file. We can't have this huge block in every documentation file, so global disable might be the right thing to do. (Although for other files, I think H1 is a good practice.)

Partially off-topic, but relevant: Now when I think about this, for Markdown documentation, we also expect to start with H2 just like we do in HTML because the file is a stub, not a complete file. We can't have this huge block in every documentation file, so global disable might be the right thing to do. (Although for other files, I think H1 is a good practice.)

Why wouldn't the new docs be complete files by themselves? (That would still have a parameters section injected)

...
Why wouldn't the new docs be complete files by themselves?

Moved to a discussion: #4211

Backported changes of .markdownlint.yml to branch 8.4.