fix(ci): make generated endpoint pages pass CI and read correctly in the sidebar

.github/scripts/detect-new-endpoints.mjs

@@ -21,6 +21,8 @@ const ROOT = process.cwd();
 const SPEC_PATH = join(ROOT, 'api-reference', 'openapi.json');
 const DOCS_JSON_PATH = join(ROOT, 'docs.json');
 const IGNORE_PATH = join(ROOT, '.api-doc-ignore');
+// Must match BASE in .github/scripts/check_frontmatter.py.
+const SITE_BASE = 'https://www.checklyhq.com/docs/';
 
 // ---------------------------------------------------------------------------
 // Tag → directory + docs.json group mapping.
@@ -163,6 +165,19 @@ function getVersionSuffix(path) {
   return match ? `-${match[1]}` : '';
 }
 
+// A page whose filename needed a version suffix sits next to another version of
+// the same operation, and both would render the same sidebar label — Mintlify
+// falls back to the spec summary when a page declares no title. Give the
+// suffixed page an explicit versioned title, unless the summary already names
+// the version itself (several /v2 operations end in "(V2)").
+function versionedTitle(ep) {
+  const suffix = getVersionSuffix(ep.path);
+  if (!suffix || ep.filename !== `${generateFilename(ep.summary)}${suffix}`) return null;
+  const version = suffix.slice(1);
+  if (new RegExp(`\\b${version}\\b`, 'i').test(ep.summary)) return null;
+  return `${ep.summary} (${version})`;
+}
+
 function getUniqueFilename(ep) {
   const baseFilename = generateFilename(ep.summary);
   const candidates = [
@@ -191,6 +206,21 @@ function getUniqueFilename(ep) {
 // docs.json updater
 // ---------------------------------------------------------------------------
 
+// Append, except for a version-suffixed page whose unsuffixed sibling is
+// already in the list — that one goes directly after the sibling so the pair
+// reads together in the sidebar instead of stranding the new version at the
+// bottom of the group.
+function insertPage(pages, pagePath) {
+  if (pages.includes(pagePath)) return;
+  const sibling = pagePath.replace(/-v\d+$/, '');
+  const siblingIdx = sibling === pagePath ? -1 : pages.indexOf(sibling);
+  if (siblingIdx === -1) {
+    pages.push(pagePath);
+    return;
+  }
+  pages.splice(siblingIdx + 1, 0, pagePath);
+}
+
 function addToDocsJson(docsJson, pagePath, groupName, subgroupName) {
   // Structure: docsJson.navigation.tabs[] → { tab: "API Reference", pages: [...] }
   const tabs = docsJson.navigation?.tabs ?? [];
@@ -231,13 +261,9 @@ function addToDocsJson(docsJson, pagePath, groupName, subgroupName) {
       targetGroup.pages.push(subgroup);
       console.log(`  + Created new subgroup "${subgroupName}" in docs.json`);
     }
-    if (!subgroup.pages.includes(pagePath)) {
-      subgroup.pages.push(pagePath);
-    }
+    insertPage(subgroup.pages, pagePath);
   } else {
-    if (!targetGroup.pages.includes(pagePath)) {
-      targetGroup.pages.push(pagePath);
-    }
+    insertPage(targetGroup.pages, pagePath);
   }
 
   return true;
@@ -304,8 +330,15 @@ function main() {
       console.log(`  + Created directory: api-reference/${ep.dir}/`);
     }
 
-    // Minimal frontmatter — Mintlify derives the title from the spec summary.
-    const mdxContent = `---\nopenapi: ${ep.method.toLowerCase()} ${ep.path}\n---\n`;
+    // Minimal frontmatter — Mintlify derives the title from the spec summary,
+    // so only version-suffixed pages need an explicit one.
+    // The canonical is self-referential and derived from the same page path
+    // docs.json gets, so it can never drift from what check_frontmatter.py
+    // expects (that check fails the PR when the key is missing or wrong).
+    const canonical = `${SITE_BASE}${docsJsonPagePath}/`;
+    const title = versionedTitle(ep);
+    const titleLine = title ? `title: '${title.replace(/'/g, "''")}'\n` : '';
+    const mdxContent = `---\nopenapi: ${ep.method.toLowerCase()} ${ep.path}\n${titleLine}canonical: '${canonical}'\n---\n`;
 
     if (!DRY_RUN) {
       writeFileSync(join(ROOT, mdxRelPath), mdxContent);

.github/workflows/update-api-spec.yml

@@ -54,14 +54,20 @@ jobs:
     - name: Generate pages for any new endpoints
       run: node .github/scripts/detect-new-endpoints.mjs
 
+    # New pages land in docs.json navigation, which is what the sitemap is
+    # generated from. Without this the static-docs-checks "Sitemap up to date"
+    # gate fails on every PR that adds an endpoint page.
+    - name: Regenerate sitemap
+      run: node .github/scripts/generate-sitemap.mjs
+
     - name: Create or update API spec PR if anything changed
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
         set -euo pipefail
 
         # Stage everything that might have changed
-        git add api-reference docs.json
+        git add api-reference docs.json sitemap.xml
 
         if git diff --cached --quiet; then
           echo "✅ No changes — nothing to do"

api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx

@@ -1,4 +1,5 @@
 ---
 openapi: get /v2/check-sessions/{checkSessionId}/completion
+title: 'Await the completion of a check session (v2)'
 canonical: 'https://www.checklyhq.com/docs/api-reference/check-sessions/await-the-completion-of-a-check-session-v2/'
 ---

api-reference/check-sessions/retrieve-a-check-session-v2.mdx

@@ -1,4 +1,5 @@
 ---
 openapi: get /v2/check-sessions/{checkSessionId}
+title: 'Retrieve a check session (v2)'
 canonical: 'https://www.checklyhq.com/docs/api-reference/check-sessions/retrieve-a-check-session-v2/'
 ---

api-reference/check-sessions/trigger-a-new-check-session-v2.mdx

@@ -1,4 +1,5 @@
 ---
 openapi: post /v2/check-sessions/trigger
+title: 'Trigger a new check session (v2)'
 canonical: 'https://www.checklyhq.com/docs/api-reference/check-sessions/trigger-a-new-check-session-v2/'
 ---

api-reference/checks/list-all-checks-v2.mdx

@@ -1,4 +1,5 @@
 ---
 openapi: get /v2/checks
+title: 'List all checks (v2)'
 canonical: 'https://www.checklyhq.com/docs/api-reference/checks/list-all-checks-v2/'
 ---

api-reference/checks/retrieve-a-check-v2.mdx

@@ -1,4 +1,5 @@
 ---
 openapi: get /v2/checks/{id}
+title: 'Retrieve a check (v2)'
 canonical: 'https://www.checklyhq.com/docs/api-reference/checks/retrieve-a-check-v2/'
 ---

docs.json

@@ -695,7 +695,9 @@
                 "group": "Checks and Monitors",
                 "pages": [
                   "api-reference/checks/list-all-checks",
+                  "api-reference/checks/list-all-checks-v2",
                   "api-reference/checks/retrieve-a-check",
+                  "api-reference/checks/retrieve-a-check-v2",
                   "api-reference/checks/delete-a-check",
                   "api-reference/checks/create-a-check",
                   "api-reference/checks/update-a-check",
@@ -759,9 +761,7 @@
                     ]
                   },
                   "api-reference/monitors/create-an-ssl-monitor",
-                  "api-reference/monitors/update-an-ssl-monitor",
-                  "api-reference/checks/list-all-checks-v2",
-                  "api-reference/checks/retrieve-a-check-v2"
+                  "api-reference/monitors/update-an-ssl-monitor"
                 ]
               },
               {
@@ -775,16 +775,16 @@
                 "group": "Check Groups",
                 "pages": [
                   "api-reference/check-groups/list-all-check-groups",
-                  "api-reference/check-groups/create-a-check-group-v2",
-                  "api-reference/check-groups/update-a-check-group-v2",
                   "api-reference/check-groups/retrieve-a-check-group",
                   "api-reference/check-groups/delete-a-check-group",
                   "api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied",
+                  "api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied-v2",
                   "api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied",
+                  "api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied-v2",
                   "api-reference/check-groups/create-a-check-group",
+                  "api-reference/check-groups/create-a-check-group-v2",
                   "api-reference/check-groups/update-a-check-group",
-                  "api-reference/check-groups/retrieve-one-check-in-a-specific-group-with-group-settings-applied-v2",
-                  "api-reference/check-groups/retrieve-all-checks-in-a-specific-group-with-group-settings-applied-v2"
+                  "api-reference/check-groups/update-a-check-group-v2"
                 ]
               },
               {