Should the Markdown documentation files be complete files with H1 or stubs? #4211
wenzeslaus
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Summary
Markdown linters consider files with H1 (level 1 heading) as the first heading as valid while starting with H2 does not pass the linting.
Our current documentation HTML files for individual tools and other units starts with H2 (I'm assuming we are keeping this for Markdown as well). The H1 heading is missing altogether at this point, but it seems it should be part of the generated header.
However, even with generated H1, the documentation files in the repository would be invalid because there is no H1 in them.
Should we consider the files to be stubs and disable the linter warning or should we make them full files with a H1 heading?
Example Markdown Documentation without H1
(Taken from #3849.)
This triggers a linter warning because it is not considered to be a valid Markdown document.
For comparison, HTML is more flexible in what is considered valid in terms of heading. My guess here is that it is due to HTML being for more general use than a Markdown document. However, H1 may have positive effect on SEO (but that can be achieved with both generated and in-file heading).
Alternative Markdown Documentation File with H1
The generated documentation would be placed after the heading or would replace the heading (e.g., with
# db.createdb - Creates an empty database
generated from the CLI). This is of course little more complex than just taking the stub and putting it in between generated header and footer.Example of the Linter Warning Elsewhere
We got the same issue with a PR template where H1 is the PR title and the template file for a PR is Markdown file which is a stub. (#4207)
How to Disable the Warning
How to disable the warning globally for Markdownlint from 954033f:
How the warning can be disable in a file (it needs also prettier behavior to be disabled) from #4207 (comment):
Initial discussion
From #4207 (comment):
Beta Was this translation helpful? Give feedback.
All reactions