Update SEO breadcrumb casing

Author: Carla Goncalves

apps/docs/src/app/api/search/route.ts

@@ -1,6 +1,7 @@
 import { createMixedbreadSearchAPI } from "fumadocs-core/search/mixedbread";
 import Mixedbread from "@mixedbread/sdk";
 import { SortedResult } from "fumadocs-core/search";
+import { formatSlugDisplayName } from "@/lib/breadcrumb-utils";
 
 export const dynamic = "force-dynamic";
 
@@ -13,13 +14,9 @@ function getBreadcrumbsFromUrl(url: string): string[] {
   const normalized = segments[0] === "v6" ? segments.slice(1) : segments;
   if (normalized.length === 0) return [];
   // Ancestors only (exclude last = current page), or full path for section roots
-  const breadcrumbSegments = normalized.length > 1 ? normalized.slice(0, -1) : normalized;
-  return breadcrumbSegments.map((s) =>
-    s
-      .split(/[-_]/)
-      .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-      .join(" "),
-  );
+  const breadcrumbSegments =
+    normalized.length > 1 ? normalized.slice(0, -1) : normalized;
+  return breadcrumbSegments.map((s) => formatSlugDisplayName(s));
 }
 
 function slugger(value: string): string {
@@ -35,7 +32,10 @@ function removeMd(md: string): string {
   if (typeof md !== "string") return "";
   try {
     return md
-      .replace(/^ {0,3}((?:-[\t ]*){3,}|(?:_[ \t]*){3,}|(?:\*[ \t]*){3,})(?:\n+|$)/gm, "")
+      .replace(
+        /^ {0,3}((?:-[\t ]*){3,}|(?:_[ \t]*){3,}|(?:\*[ \t]*){3,})(?:\n+|$)/gm,
+        "",
+      )
       .replace(/^([\s\t]*)([*\-+]|\d+\.)\s+/gm, "$1")
       .replace(/\n={2,}/g, "\n")
       .replace(/^[=-]{2,}\s*$/gm, "")
@@ -49,7 +49,10 @@ function removeMd(md: string): string {
       .replace(/!\[(.*?)\][[(].*?[\])]/g, "")
       .replace(/\[([\s\S]*?)\]\s*[([].*?[)\]]/g, "$1")
       .replace(/^(\n)?\s{0,3}>\s?/gm, "$1")
-      .replace(/^(\n)?\s{0,}#{1,6}\s*( (.+))? +#+$|^(\n)?\s{0,}#{1,6}\s*( (.+))?$/gm, "$1$3$4$6")
+      .replace(
+        /^(\n)?\s{0,}#{1,6}\s*( (.+))? +#+$|^(\n)?\s{0,}#{1,6}\s*( (.+))?$/gm,
+        "$1$3$4$6",
+      )
       .replace(/([*]+)(\S)(.*?\S)??\1/g, "$2$3")
       .replace(/(^|\W)([_]+)(\S)(.*?\S)??\2($|\W)/g, "$1$3$4$5")
       .replace(/(`{3,})(.*?)\1/gm, "$2")
@@ -88,7 +91,8 @@ export const { GET } = createMixedbreadSearchAPI({
           breadcrumbs,
         },
       ];
-      const heading = item.type === "text" ? extractHeadingTitle(item.text) : "";
+      const heading =
+        item.type === "text" ? extractHeadingTitle(item.text) : "";
       if (heading)
         chunkResults.push({
           id: `${base}-heading`,

apps/docs/src/components/structured-data.tsx

@@ -1,4 +1,5 @@
 import { getBaseUrl, withDocsBasePath } from "@/lib/urls";
+import { formatSlugDisplayName } from "@/lib/breadcrumb-utils";
 import type { InferPageType } from "fumadocs-core/source";
 import type { source, sourceV6 } from "@/lib/source";
 import { JsonLd } from "@prisma-docs/ui/components/json-ld";
@@ -42,7 +43,9 @@ function getSectionTitle(page: DocsPage, slugs: string[]) {
 
   for (const candidatePath of candidatePaths) {
     try {
-      const meta = JSON.parse(readFileSync(candidatePath, "utf8")) as { title?: string };
+      const meta = JSON.parse(readFileSync(candidatePath, "utf8")) as {
+        title?: string;
+      };
       if (typeof meta.title === "string" && meta.title.trim().length > 0) {
         sectionTitleCache.set(cacheKey, meta.title);
         return meta.title;
@@ -61,14 +64,16 @@ function getBreadcrumbName(page: DocsPage, slugs: string[], index: number) {
 
   return (
     getSectionTitle(page, slugs.slice(0, index + 1)) ??
-    slugs[index].charAt(0).toUpperCase() + slugs[index].slice(1).replace(/-/g, " ")
+    formatSlugDisplayName(slugs[index])
   );
 }
 
 export function TechArticleSchema({ page }: StructuredDataProps) {
   const baseUrl = getBaseUrl();
-  const lastModified = (page.data as { lastModified?: Date | string }).lastModified;
-  const datePublished = (page.data as { datePublished?: Date | string }).datePublished;
+  const lastModified = (page.data as { lastModified?: Date | string })
+    .lastModified;
+  const datePublished = (page.data as { datePublished?: Date | string })
+    .datePublished;
 
   const schema = {
     "@context": "https://schema.org",

apps/docs/src/lib/breadcrumb-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * Maps individual slug words (after splitting on hyphens/underscores) to their
+ * correct display form. Handles acronyms, initialisms, and proper names that
+ * simple title-casing gets wrong.
+ *
+ * Keys MUST be lowercase.
+ */
+const WORD_DISPLAY_MAP: Record<string, string> = {
+  // Initialisms / acronyms
+  ai: 'AI',
+  api: 'API',
+  cli: 'CLI',
+  crud: 'CRUD',
+  css: 'CSS',
+  csv: 'CSV',
+  db: 'DB',
+  ddl: 'DDL',
+  dns: 'DNS',
+  html: 'HTML',
+  http: 'HTTP',
+  https: 'HTTPS',
+  iac: 'IaC',
+  id: 'ID',
+  ids: 'IDs',
+  json: 'JSON',
+  jwt: 'JWT',
+  mdx: 'MDX',
+  orm: 'ORM',
+  pgx: 'PGX',
+  pql: 'PQL',
+  sdk: 'SDK',
+  sql: 'SQL',
+  ssl: 'SSL',
+  tcp: 'TCP',
+  tls: 'TLS',
+  url: 'URL',
+  urls: 'URLs',
+  xml: 'XML',
+  // Proper names / compound words that don't split on hyphens
+  authjs: 'Auth.js',
+  nextauth: 'NextAuth',
+  postgresql: 'PostgreSQL',
+  mysql: 'MySQL',
+  mongodb: 'MongoDB',
+  cockroachdb: 'CockroachDB',
+  planetscale: 'PlanetScale',
+};
+
+/**
+ * Converts a raw URL slug segment into a human-readable display name, correctly
+ * casing acronyms, initialisms, and known proper names.
+ *
+ * The slug is split on hyphens and underscores; each token is looked up in
+ * {@link WORD_DISPLAY_MAP} (case-insensitively) and, if not found, is given a
+ * simple initial-capital. Tokens are then joined with a single space.
+ *
+ * @example
+ * formatSlugDisplayName('orm')              // → 'ORM'
+ * formatSlugDisplayName('prisma-client')    // → 'Prisma Client'
+ * formatSlugDisplayName('management-api')   // → 'Management API'
+ * formatSlugDisplayName('using-raw-sql')    // → 'Using Raw SQL'
+ * formatSlugDisplayName('platform-cli')     // → 'Platform CLI'
+ * formatSlugDisplayName('api-reference')    // → 'API Reference'
+ * formatSlugDisplayName('authjs')           // → 'Auth.js'
+ */
+export function formatSlugDisplayName(slug: string): string {
+  return slug
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((word) => {
+      const key = word.toLowerCase();
+      return WORD_DISPLAY_MAP[key] ?? word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+    })
+    .join(' ');
+}