fix(docs): inject required frontmatter and fix naming collisions in generated API docs

The generate-docs.ts beforeWrite hook was missing url, metaTitle, and
metaDescription fields required by source.config.ts. Additionally, the
naming regex stripped ById entirely, causing list and get-by-id endpoints
to collide on the same filename and corrupt each other's content.

generate-docs.ts:
- Derive and inject url, metaTitle, metaDescription from operation metadata
- Fix naming regex (By[A-Z][a-z]* -> By[A-Z][a-z]{2,}) to preserve ById
- Use slice-based content replacement to prevent corruption

sync-management-api-docs.yml:
- Clean stale MDX files before generation
- Run lint:links, lint:spellcheck, and next build before committing
- Gate commit, push, and Vercel deploy on changes detected

Author: kristof-siket

.github/workflows/sync-management-api-docs.yml

@@ -35,6 +35,9 @@ jobs:
         working-directory: apps/docs
         run: pnpm fetch-openapi
 
+      - name: Clean stale endpoint files
+        run: find apps/docs/content/docs/management-api/endpoints -name '*.mdx' -type f -delete
+
       - name: Generate docs
         working-directory: apps/docs
         run: pnpm tsx scripts/generate-docs.ts
@@ -51,6 +54,19 @@ jobs:
             git status --short -- apps/docs/content/docs/management-api/
           fi
 
+      - name: Validate links
+        if: steps.changes.outputs.changed == 'true'
+        run: pnpm run lint:links
+
+      - name: Validate spelling
+        if: steps.changes.outputs.changed == 'true'
+        run: pnpm run lint:spellcheck
+
+      - name: Build docs
+        if: steps.changes.outputs.changed == 'true'
+        working-directory: apps/docs
+        run: pnpm exec next build
+
       - name: Commit and push
         if: steps.changes.outputs.changed == 'true'
         run: |
@@ -61,4 +77,5 @@ jobs:
           git push "https://x-access-token:${{ secrets.BOT_TOKEN_DOCS_COMMIT }}@github.com/${{ github.repository }}.git" HEAD:${{ github.ref_name }}
 
       - name: Trigger Vercel deploy
+        if: steps.changes.outputs.changed == 'true'
         run: curl --fail -X POST "${{ secrets.VERCEL_DEPLOY_HOOK_URL }}"

apps/docs/scripts/generate-docs.ts

@@ -16,7 +16,7 @@ void generateFiles({
 
       const cleanName = operationId
         .replace(/V\d+/g, "")
-        .replace(/By[A-Z][a-z]*/g, "")
+        .replace(/By[A-Z][a-z]{2,}/g, "")
         .replace(/([a-z])([A-Z])/g, "$1-$2")
         .toLowerCase();
 
@@ -28,29 +28,65 @@ void generateFiles({
   beforeWrite(files) {
     for (const file of files) {
       const frontmatterMatch = file.content.match(/^---\n([\s\S]*?)\n---/);
-      if (frontmatterMatch) {
-        const frontmatter = frontmatterMatch[1];
-        if (frontmatter.includes("_openapi:")) {
-          const apiPageMatch = file.content.match(/<APIPage[^>]*operations=\{(\[.*?\])\}/s);
-          if (apiPageMatch) {
-            try {
-              const operations = JSON.parse(apiPageMatch[1].replace(/'/g, '"'));
-              if (operations[0]?.path) {
-                const path = operations[0].path;
-
-                const updatedFrontmatter = frontmatter.replace(
-                  /(_openapi:\s*\n\s*method:)/,
-                  `_openapi:\n  path: "${path}"\n  method:`,
-                );
-
-                file.content = file.content.replace(frontmatter, updatedFrontmatter);
-              }
-            } catch (e) {
-              console.warn(`Failed to parse operations for ${file.path}:`, e);
-            }
+      if (!frontmatterMatch) continue;
+
+      let frontmatter = frontmatterMatch[1];
+
+      const titleMatch = frontmatter.match(/^title:\s*(.+)$/m);
+      const title = titleMatch
+        ? titleMatch[1].replace(/^['"]|['"]$/g, "")
+        : "";
+
+      const methodMatch = frontmatter.match(/method:\s*(\w+)/);
+      const method = methodMatch ? methodMatch[1].toUpperCase() : "";
+
+      const apiPageMatch = file.content.match(
+        /<APIPage[^>]*operations=\{(\[.*?\])\}/s,
+      );
+      let apiPath = "";
+      if (apiPageMatch) {
+        try {
+          const operations = JSON.parse(apiPageMatch[1].replace(/'/g, '"'));
+          if (operations[0]?.path) {
+            apiPath = operations[0].path;
           }
+        } catch (e) {
+          console.warn(`Failed to parse operations for ${file.path}:`, e);
         }
       }
+
+      if (
+        frontmatter.includes("_openapi:") &&
+        !frontmatter.includes("path:") &&
+        apiPath
+      ) {
+        frontmatter = frontmatter.replace(
+          /(_openapi:\s*\n\s*method:)/,
+          `_openapi:\n  path: "${apiPath}"\n  method:`,
+        );
+      }
+
+      const contentAfterFrontmatter = file.content.slice(
+        frontmatterMatch[0].length,
+      );
+      const descMatch = contentAfterFrontmatter.match(/\n\n([^<\n{][^\n]+)\n/);
+      const description = descMatch ? descMatch[1].trim() : title;
+
+      const slug = file.path
+        .replace(/^.*endpoints\//, "")
+        .replace(/\.mdx$/, "");
+      const urlPath = `/management-api/endpoints/${slug}`;
+      const metaTitle = `${method} ${apiPath} | ${title} - Prisma Postgres`;
+      const descriptionClean = description.replace(/\.$/, "");
+      const metaDescription = `Management API: ${descriptionClean}. ${method} ${apiPath}.`;
+
+      frontmatter += `\nurl: ${urlPath}`;
+      frontmatter += `\nmetaTitle: '${metaTitle.replace(/'/g, "''")}'`;
+      frontmatter += `\nmetaDescription: '${metaDescription.replace(/'/g, "''")}'`;
+
+      file.content =
+        `---\n${frontmatter}\n---` +
+        file.content.slice(frontmatterMatch[0].length);
     }
   },
 });