Docs: exceptions and guidelines for linters
Here's an example for when linting blocks an attempt to increase the document quality and a proposal to open linters for exceptions, as well as to create a guideline for adding new linters.
Problem to solve
When revamping a document (!30230 (comment 329397551)), I changed its headings. To keep the same anchors to avoid breaking links, I used Kramdown's custom ID markup to do so. But I cannot use it as the markdown linter doesn't allow me to do so.
The importance to preserve the anchor is that for external resources liking to this document, changing the heading would break the anchor links.
Further details
I changed a heading from ### Check if Git has already been installed
to ### Install Git
but wanted to keep the same anchor. There are two ways to do this using Kramdown markup:
1st:
### Install Git
{: #check-if-git-has-already-been-installed}
But this is forbidden by the markdownlint
rule Headings should be surrounded by blank lines.
2nd:
### Install Git {#check-if-git-has-already-been-installed}
But it fails the rule Proper names should have the correct capitalization.
Finally, I had the idea of hardcoding HTML and thought that it would resolve the problem:
<h3 id="check-if-git-has-already-been-installed">Install Git</h3>
But, again, it's a no-go because Kramdown doesn't understand that this is a heading so it doesn't add an entry to the doc's table of content. (Screenshot here).
Proposal
Evaluate carefully the addition of new linter rules and create a way to accept exceptions. At the same time that we want to save TW's review time and keep high-quality docs, we need to consider that:
- We have tons of contributors to the docs and we shouldn't make it hard for them to contribute.
- We need to be able to deal with exceptions.
Please note: this issue describes an example for smt we cannot do bc of the linters and proposes that we find a solution for exceptions like this. Also, I think we need a guideline for adding linters so that we do not make it hard to contribute to the docs, given the huge number of contributors we have.
Who can address the issue
Docs team, the specialists in linters.