From 0f1512d852b9923999018ba1ad44ab1fad6c4322 Mon Sep 17 00:00:00 2001
From: Julius Volz <julius.volz@gmail.com>
Date: Thu, 3 Jul 2025 23:17:05 +0200
Subject: [PATCH] Use new frontmatter docs title schema for new
 Prometheus/Alertmanager docs (#2686)

Signed-off-by: Julius Volz <julius.volz@gmail.com>
---
 scripts/utils.ts                | 10 ++++++++++
 src/app/docs/[...slug]/page.tsx | 17 ++++++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/scripts/utils.ts b/scripts/utils.ts
index d0b0da2c..763c8c23 100644
--- a/scripts/utils.ts
+++ b/scripts/utils.ts
@@ -10,6 +10,16 @@ export const compareFullVersion = (a: string, b: string) => {
   return compare(a.replace(/^v/, ""), b.replace(/^v/, ""));
 };
 
+// Compares two "<major>.<minor>" version strings., e.g. "3.4" vs "3.5".
+export const compareMajorMinor = (a: string, b: string) => {
+  const [aMajor, aMinor] = a.split(".").map(Number);
+  const [bMajor, bMinor] = b.split(".").map(Number);
+  if (aMajor === bMajor) {
+    return aMinor === bMinor ? 0 : aMinor > bMinor ? 1 : -1;
+  }
+  return aMajor > bMajor ? 1 : -1;
+};
+
 export function filterUnique(value: string, index: number, array: string[]) {
   return array.indexOf(value) === index;
 }
diff --git a/src/app/docs/[...slug]/page.tsx b/src/app/docs/[...slug]/page.tsx
index 7ea7a23a..c184b2b8 100644
--- a/src/app/docs/[...slug]/page.tsx
+++ b/src/app/docs/[...slug]/page.tsx
@@ -8,6 +8,7 @@ import { Divider, Title } from "@mantine/core";
 import PrevNextEditButtons from "./PrevNextEditButtons";
 import path from "path";
 import { DocMetadata } from "@/docs-collection-types";
+import { compareMajorMinor } from "../../../../scripts/utils";
 
 // Next.js uses this function at build time to figure out which
 // docs pages it should statically generate.
@@ -82,6 +83,18 @@ export default async function DocsPage({
     (docMeta.version === docMeta.latestVersion &&
       !docMeta.slug.startsWith(docMeta.versionRoot));
 
+  // The Markdown format was changed in Prometheus >3.4 and Alertmanager >0.28
+  // to not include the H1 title in the Markdown content itself, so we need to
+  // externally render the title using the frontmatter `title` field instead..
+  const useFrontmatterTitle =
+    docMeta.type === "local-doc" ||
+    (docMeta.type === "repo-doc" &&
+      docMeta.owner === "prometheus" &&
+      ((docMeta.repo === "prometheus" &&
+        compareMajorMinor(docMeta.version, "3.4") === 1) ||
+        (docMeta.repo === "alertmanager" &&
+          compareMajorMinor(docMeta.version, "0.28") === 1)));
+
   return (
     <>
       <VersionWarning currentPage={docMeta} />
@@ -93,9 +106,7 @@ export default async function DocsPage({
           )}`,
         }}
       >
-        {docMeta.type === "local-doc" && (
-          <Title order={1}>{docMeta.title}</Title>
-        )}
+        {useFrontmatterTitle && <Title order={1}>{docMeta.title}</Title>}
         <PromMarkdown
           normalizeHref={(href: string | undefined) => {
             if (!href) {