PR for this at https://github.com/prometheus/docs/pull/2662
On Wed, May 28, 2025 at 3:59 PM Julius Volz <[email protected]> wrote: > 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 > -- You received this message because you are subscribed to the Google Groups "Prometheus Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/prometheus-developers/CA%2BT6YoyPOz2S_JHw0%3DRdfwk3uB9KhPJ1RnJ7ivqBG24-iDEohw%40mail.gmail.com.
