feat(docs): add BreadcrumbList JSON-LD to guide pages (supabase#45477)

## Summary

Emits `BreadcrumbList` JSON-LD on every `/docs/guides/*` page served by
`GuideTemplate`. Search engines and AI crawlers get an explicit
hierarchical signal for the docs site (the marketing site already
shipped JSON-LD via supabase#45451). The chain prepends `Docs > Guides` to the
existing resolver output, so a page like `/docs/guides/auth/passwords`
produces a 5-level chain with the leaf URL set per Google's spec.

## Changes

- New `apps/docs/lib/breadcrumbs.ts`: pure pathname → chain resolver,
server-safe. Extracted from the existing client `useBreadcrumbs` hook so
the same logic runs in both contexts.
- New `apps/docs/lib/json-ld.ts`: `serializeJsonLd` +
`breadcrumbListSchema` mirroring `apps/www/lib/json-ld.ts`.
- `Breadcrumbs.tsx` (visual) now delegates to the shared resolver —
single source of truth for visual + SEO chains.
- `GuideTemplate` takes a required `pathname` prop and emits `<script
type="application/ld+json">` next to `<Breadcrumbs />`. Skipped when the
chain is empty (e.g., page not in nav menu). Middle items without URLs
(e.g., the "Auth" section root) omit `item`, matching the visual
breadcrumb.
- 8 explicit-prop callers updated; `[[...slug]]` callers already spread
`data` (which carries `pathname`).

## Scope

**Out of scope:**
- `/docs/reference/*` (SDK reference) — no breadcrumbs rendered today,
would need separate traversal over spec JSON.
- `/guides/troubleshooting/*` — uses its own template, not
`GuideTemplate`.
- `TechArticle` per-page schema — high maintenance for marginal value.

## Testing (Vercel preview)

```bash
curl -s https://<preview>/docs/guides/auth/passwords | grep -oE '<script type="application/ld\+json"[^>]*>[^<]+</script>'
```

Expect a script tag with the chain `Docs > Guides > Auth > Flows
(How-tos) > Password-based`, leaf URL
`https://supabase.com/docs/guides/auth/passwords`.

- [x] `/docs/guides/auth/passwords` — 5-item chain, leaf URL present
- [x] `/docs/guides/getting-started/features` — 4-item chain, all items
have URLs
- [x] `/docs/guides/getting-started/ai-prompts/<slug>` — special-case
chain (`Getting started > AI Tools > Prompts > <slug>`), leaf URL falls
back to pathname
- [x] `/docs/guides/database/database-advisors` (explicit-prop caller) —
chain renders
- [x] Visual breadcrumb on the same pages still renders correctly
- [ ] Validate output through [Google Rich Results
Test](https://search.google.com/test/rich-results) on a deployed preview
URL
- [x] `/docs/guides/troubleshooting/<slug>` — no JSON-LD emitted
(different template, intentional)

## Linear

- fixes GROWTH-820

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added JSON-LD breadcrumb markup to guide pages to improve
search/discovery.

* **Improvements**
* Centralized breadcrumb generation for consistent, accurate breadcrumbs
across guides.
* Multiple guide pages updated to ensure breadcrumbs and page context
display correctly.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: pamelachia

apps/docs/app/guides/database/database-advisors/page.tsx

@@ -1,18 +1,17 @@
-import { capitalize } from 'lodash-es'
-import rehypeSlug from 'rehype-slug'
-import { Heading } from 'ui'
-import { Admonition } from 'ui-patterns'
-
 import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
 import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
-import { OCTOKIT_RETRY_OPTIONS, getGitHubFileContents, octokit } from '~/lib/octokit'
 import { TabPanel, Tabs } from '~/features/ui/Tabs'
-import { UrlTransformFunction, linkTransform } from '~/lib/mdx/plugins/rehypeLinkTransform'
+import { linkTransform, UrlTransformFunction } from '~/lib/mdx/plugins/rehypeLinkTransform'
 import remarkMkDocsAdmonition from '~/lib/mdx/plugins/remarkAdmonition'
 import { removeTitle } from '~/lib/mdx/plugins/remarkRemoveTitle'
 import remarkPyMdownTabs from '~/lib/mdx/plugins/remarkTabs'
+import { getGitHubFileContents, octokit, OCTOKIT_RETRY_OPTIONS } from '~/lib/octokit'
 import { SerializeOptions } from '~/types/next-mdx-remote-serialize'
+import { capitalize } from 'lodash-es'
+import rehypeSlug from 'rehype-slug'
+import { Heading } from 'ui'
+import { Admonition } from 'ui-patterns'
 
 // We fetch these docs at build time from an external repo
 const org = 'supabase'
@@ -64,7 +63,7 @@ const DatabaseAdvisorDocs = async () => {
   } as SerializeOptions
 
   return (
-    <GuideTemplate meta={meta} editLink={editLink}>
+    <GuideTemplate meta={meta} editLink={editLink} pathname="/guides/database/database-advisors">
       <MDXRemoteBase source={markdownIntro} />
       <Heading tag="h2">Available checks</Heading>
 

apps/docs/app/guides/deployment/terraform/reference/page.tsx

@@ -352,7 +352,11 @@ const TerraformReferencePage = async () => {
   const editLink = newEditLink('supabase/terraform-provider-supabase')
 
   return (
-    <GuideTemplate meta={meta} editLink={editLink}>
+    <GuideTemplate
+      meta={meta}
+      editLink={editLink}
+      pathname="/guides/deployment/terraform/reference"
+    >
       The Terraform Provider provides access to{' '}
       <Link
         href="https://developer.hashicorp.com/terraform/language/resources"

apps/docs/app/guides/getting-started/ai-prompts/[slug]/page.tsx

@@ -1,6 +1,7 @@
+import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
 import { source } from 'common-tags'
 import { notFound } from 'next/navigation'
-import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
+
 import {
   generateAiPromptMetadata,
   generateAiPromptsStaticParams,
@@ -50,6 +51,7 @@ export default async function AiPromptsPage(props: { params: Promise<{ slug: str
       meta={{ title: `AI Prompt: ${heading}` }}
       content={content}
       editLink={newEditLink(`supabase/supabase/blob/master/examples/prompts/${slug}.md`)}
+      pathname={`/guides/getting-started/ai-prompts/${slug}`}
     />
   )
 }

apps/docs/app/guides/local-development/cli/config/page.tsx

@@ -36,7 +36,7 @@ const Config = () => {
   const editLink = newEditLink('supabase/supabase/blob/master/apps/docs/spec/cli_v1_config.yaml')
 
   return (
-    <GuideTemplate meta={meta} editLink={editLink}>
+    <GuideTemplate meta={meta} editLink={editLink} pathname="/guides/local-development/cli/config">
       <ReactMarkdown>{specFile.info.description}</ReactMarkdown>
       <div>{content}</div>
     </GuideTemplate>

apps/docs/app/guides/self-hosting/analytics/config/page.tsx

@@ -1,6 +1,6 @@
 import Param from '~/components/Params'
-import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
+import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
 import specAnalyticsV0 from '~/spec/analytics_v0_config.yaml' with { type: 'yml' }
 
@@ -23,6 +23,7 @@ const AnalyticsConfigPage = async () => {
       editLink={newEditLink(
         'supabase/supabase/blob/master/apps/docs/app/guides/self-hosting/analytics/config/page.tsx'
       )}
+      pathname="/guides/self-hosting/analytics/config"
     >
       <MDXRemoteBase source={descriptionMdx} />
 

apps/docs/app/guides/self-hosting/auth/config/page.tsx

@@ -1,6 +1,6 @@
 import Param from '~/components/Params'
-import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
+import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
 import specAuthV1 from '~/spec/gotrue_v1_config.yaml' with { type: 'yml' }
 
@@ -23,6 +23,7 @@ const AuthConfigPage = async () => {
       editLink={newEditLink(
         'supabase/supabase/blob/master/apps/docs/app/guides/self-hosting/auth/config/page.tsx'
       )}
+      pathname="/guides/self-hosting/auth/config"
     >
       <MDXRemoteBase source={descriptionMdx} />
 

apps/docs/app/guides/self-hosting/realtime/config/page.tsx

@@ -1,6 +1,6 @@
 import Param from '~/components/Params'
-import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
+import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
 import specRealtimeV0 from '~/spec/realtime_v0_config.yaml' with { type: 'yml' }
 
@@ -23,6 +23,7 @@ const RealtimeConfigPage = async () => {
       editLink={newEditLink(
         'supabase/supabase/blob/master/apps/docs/app/guides/self-hosting/realtime/config/page.tsx'
       )}
+      pathname="/guides/self-hosting/realtime/config"
     >
       <MDXRemoteBase source={descriptionMdx} />
 

apps/docs/app/guides/self-hosting/storage/config/page.tsx

@@ -1,6 +1,6 @@
 import Param from '~/components/Params'
-import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
+import { genGuideMeta } from '~/features/docs/GuidesMdx.utils'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
 import specStorageV0 from '~/spec/storage_v0_config.yaml' with { type: 'yml' }
 
@@ -23,6 +23,7 @@ const StorageConfigPage = async () => {
       editLink={newEditLink(
         'supabase/supabase/blob/master/apps/docs/app/guides/self-hosting/storage/config/page.tsx'
       )}
+      pathname="/guides/self-hosting/storage/config"
     >
       <MDXRemoteBase source={descriptionMdx} />
 

apps/docs/components/Breadcrumbs.tsx

@@ -1,18 +1,18 @@
 'use client'
 
+import { resolveBreadcrumbs } from '~/lib/breadcrumbs'
+import { useBreakpoint } from 'common'
 import Link from 'next/link'
 import { usePathname, useSearchParams } from 'next/navigation'
 import React, { Fragment, Suspense } from 'react'
-
-import { useBreakpoint } from 'common'
 import {
   Breadcrumb_Shadcn_ as Breadcrumb,
-  BreadcrumbList_Shadcn_ as BreadcrumbList,
+  BreadcrumbEllipsis_Shadcn_ as BreadcrumbEllipsis,
   BreadcrumbItem_Shadcn_ as BreadcrumbItem,
   BreadcrumbLink_Shadcn_ as BreadcrumbLink,
-  BreadcrumbSeparator_Shadcn_ as BreadcrumbSeparator,
+  BreadcrumbList_Shadcn_ as BreadcrumbList,
   BreadcrumbPage_Shadcn_ as BreadcrumbPage,
-  BreadcrumbEllipsis_Shadcn_ as BreadcrumbEllipsis,
+  BreadcrumbSeparator_Shadcn_ as BreadcrumbSeparator,
   Button,
   cn,
   Drawer,
@@ -26,9 +26,6 @@ import {
   DropdownMenuTrigger,
 } from 'ui'
 
-import * as NavItems from '~/components/Navigation/NavigationMenu/NavigationMenu.constants'
-import { getMenuId } from '~/components/Navigation/NavigationMenu/NavigationMenu.utils'
-
 interface BreadcrumbsProps extends React.HTMLAttributes<HTMLDivElement> {
   minLength?: number
   forceDisplayOnMobile?: boolean
@@ -159,56 +156,5 @@ const BreadcrumbsInternal = ({
 
 function useBreadcrumbs() {
   const pathname = usePathname()
-
-  const isTroubleshootingPage = pathname.startsWith('/guides/troubleshooting')
-  if (isTroubleshootingPage) {
-    const breadcrumbs = [{ name: 'Troubleshooting', url: '/guides/troubleshooting' }]
-    return breadcrumbs
-  }
-
-  const isAiPromptsPage = pathname.startsWith('/guides/getting-started/ai-prompts')
-  if (isAiPromptsPage) {
-    const breadcrumbs = [
-      { name: 'Getting started', url: '/guides/getting-started' },
-      { name: 'AI Tools' },
-      { name: 'Prompts', url: '/guides/getting-started/ai-prompts' },
-    ]
-    return breadcrumbs
-  }
-
-  // TODO: Breadcrumbs currently can't infer the "AI Tools" parent for /guides/getting-started/ai-* routes,
-  // so we special-case these paths here. Remove when Breadcrumbs can derive this hierarchy from NavigationMenu.
-  const isAiSkillsPage = pathname.startsWith('/guides/getting-started/ai-skills')
-  if (isAiSkillsPage) {
-    const breadcrumbs = [
-      { name: 'Getting started', url: '/guides/getting-started' },
-      { name: 'AI Tools' },
-      { name: 'Agent Skills', url: '/guides/getting-started/ai-skills' },
-    ]
-    return breadcrumbs
-  }
-
-  const menuId = getMenuId(pathname)
-  const menu = NavItems[menuId]
-  return findMenuItemByUrl(menu, pathname, [])
-}
-
-function findMenuItemByUrl(menu: any, targetUrl: string, parents: any[] = []) {
-  // If the menu has items, recursively search through them
-  if (menu.items) {
-    for (let item of menu.items) {
-      const result = findMenuItemByUrl(item, targetUrl, [...parents, menu])
-      if (result) {
-        return result
-      }
-    }
-  }
-
-  // Check if the current menu object itself has the target URL
-  if (menu.url === targetUrl) {
-    return [...parents, menu]
-  }
-
-  // If the URL is not found, return null
-  return null
+  return resolveBreadcrumbs(pathname)
 }

apps/docs/features/docs/GuidesMdx.template.tsx

@@ -1,16 +1,16 @@
-import { ExternalLink } from 'lucide-react'
-import { type ReactNode } from 'react'
-import ReactMarkdown from 'react-markdown'
-
-import { cn } from 'ui'
-
 import Breadcrumbs from '~/components/Breadcrumbs'
 import GuidesSidebar from '~/components/GuidesSidebar'
 import { TocAnchorsProvider } from '~/features/docs/GuidesMdx.client'
 import { MDXRemoteBase } from '~/features/docs/MdxBase'
 import type { WithRequired } from '~/features/helpers.types'
+import { resolveBreadcrumbs } from '~/lib/breadcrumbs'
 import { type GuideFrontmatter } from '~/lib/docs'
+import { breadcrumbListSchema, serializeJsonLd } from '~/lib/json-ld'
 import { SerializeOptions } from '~/types/next-mdx-remote-serialize'
+import { ExternalLink } from 'lucide-react'
+import { type ReactNode } from 'react'
+import ReactMarkdown from 'react-markdown'
+import { cn } from 'ui'
 
 const EDIT_LINK_SYMBOL = Symbol('edit link')
 interface EditLink {
@@ -54,14 +54,27 @@ interface BaseGuideTemplateProps {
   children?: ReactNode
   editLink: EditLink
   mdxOptions?: SerializeOptions
+  pathname: `/${string}`
 }
 
 type GuideTemplateProps =
   | WithRequired<BaseGuideTemplateProps, 'children'>
   | WithRequired<BaseGuideTemplateProps, 'content'>
 
-const GuideTemplate = ({ meta, content, children, editLink, mdxOptions }: GuideTemplateProps) => {
+const GuideTemplate = ({
+  meta,
+  content,
+  children,
+  editLink,
+  mdxOptions,
+  pathname,
+}: GuideTemplateProps) => {
   const hideToc = meta?.hideToc || meta?.hide_table_of_contents
+  const breadcrumbChain = resolveBreadcrumbs(pathname)
+  const breadcrumbJsonLd =
+    breadcrumbChain.length > 0
+      ? serializeJsonLd(breadcrumbListSchema({ pathname, chain: breadcrumbChain }))
+      : null
 
   return (
     <TocAnchorsProvider>
@@ -74,6 +87,12 @@ const GuideTemplate = ({ meta, content, children, editLink, mdxOptions }: GuideT
             'col-span-12 md:col-span-9'
           )}
         >
+          {breadcrumbJsonLd && (
+            <script
+              type="application/ld+json"
+              dangerouslySetInnerHTML={{ __html: breadcrumbJsonLd }}
+            />
+          )}
           <Breadcrumbs className="mb-2" />
           <article
             // Used to get headings for the table of contents