PR for this at https://github.com/prometheus/docs/pull/2662
On Wed, May 28, 2025 at 3:59 PM Julius Volz <julius.v...@gmail.com> 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 prometheus-developers+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/prometheus-developers/CA%2BT6YoyPOz2S_JHw0%3DRdfwk3uB9KhPJ1RnJ7ivqBG24-iDEohw%40mail.gmail.com.
