Standardizing title / nav_title / H1 usage in Markdown docs

[Julius Volz]

Heads up:

I'm looking to unify how we use page titles in our documentation Markdown pages. Currently we have a wild mix:

For documentation pages, we do:

* First H1 (`# Heading`) in the Markdown content becomes the displayed title on the page itself
* `title` frontmatter field is used in the side nav and prev/next buttons, except if `nav_title` exists, in which case `title` is used for nothing at all and just becomes dead weight

For blog posts, we do:

* No initial H1 (`# Heading`) in the Markdown content
* `title` field is used to create an H1 when rendering the page

To reduce inconsistencies and redundancies, I want to standardize for docs on the same model we currently only use for blog posts, where there is no H1 in the Markdown itself, and the `title` field is what is used to generate the displayed title on the final page. So there would always be a `title` field in the frontmatter, optionally a `nav_title` (for shorter titles in navs), and then the main content would only start at using H2 elements for sections. I'd also standardize on not using Title Case for titles, as we mostly already do, but not everywhere.

For the docs pulled from external repos (Prometheus + Alertmanager), I would then manage the transition based on the external repo's version number (e.g. "If the docs come from Prometheus >=3.5, then assume the new schema, otherwise use the H1 in the Markdown itself for the page title")

Gonna work on a set of PRs to that effect, unless someone objects.

Cheers,

Julius

[Julius Volz]

PR for this at https://github.com/prometheus/docs/pull/2662