Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

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

Pamela Chia5ce163fd6938
diff --git a/apps/docs/app/guides/database/database-advisors/page.tsx b/apps/docs/app/guides/database/database-advisors/page.tsx
index 889dff9b749..e35e9da410c 100644
--- a/apps/docs/app/guides/database/database-advisors/page.tsx
+++ b/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>
diff --git a/apps/docs/app/guides/deployment/terraform/reference/page.tsx b/apps/docs/app/guides/deployment/terraform/reference/page.tsx
index 93029a2c0d1..220d551479a 100644
--- a/apps/docs/app/guides/deployment/terraform/reference/page.tsx
+++ b/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"
diff --git a/apps/docs/app/guides/getting-started/ai-prompts/[slug]/page.tsx b/apps/docs/app/guides/getting-started/ai-prompts/[slug]/page.tsx
index 82f3837575d..1213cb07a74 100644
--- a/apps/docs/app/guides/getting-started/ai-prompts/[slug]/page.tsx
+++ b/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}`}
/>
)
}
diff --git a/apps/docs/app/guides/local-development/cli/config/page.tsx b/apps/docs/app/guides/local-development/cli/config/page.tsx
index 75a28a947e0..124ade3a74c 100644
--- a/apps/docs/app/guides/local-development/cli/config/page.tsx
+++ b/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>
diff --git a/apps/docs/app/guides/self-hosting/analytics/config/page.tsx b/apps/docs/app/guides/self-hosting/analytics/config/page.tsx
index 5874b2b40dd..2c28fa2bf44 100644
--- a/apps/docs/app/guides/self-hosting/analytics/config/page.tsx
+++ b/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} />
diff --git a/apps/docs/app/guides/self-hosting/auth/config/page.tsx b/apps/docs/app/guides/self-hosting/auth/config/page.tsx
index 4ba779c8304..4221f2f7f42 100644
--- a/apps/docs/app/guides/self-hosting/auth/config/page.tsx
+++ b/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} />
diff --git a/apps/docs/app/guides/self-hosting/realtime/config/page.tsx b/apps/docs/app/guides/self-hosting/realtime/config/page.tsx
index 6d3ce48ccaf..80076742be8 100644
--- a/apps/docs/app/guides/self-hosting/realtime/config/page.tsx
+++ b/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} />
diff --git a/apps/docs/app/guides/self-hosting/storage/config/page.tsx b/apps/docs/app/guides/self-hosting/storage/config/page.tsx
index 88c71034cd9..c6682ce7add 100644
--- a/apps/docs/app/guides/self-hosting/storage/config/page.tsx
+++ b/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} />
diff --git a/apps/docs/components/Breadcrumbs.tsx b/apps/docs/components/Breadcrumbs.tsx
index b9bde64e769..3e524100491 100644
--- a/apps/docs/components/Breadcrumbs.tsx
+++ b/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)
}
diff --git a/apps/docs/features/docs/GuidesMdx.template.tsx b/apps/docs/features/docs/GuidesMdx.template.tsx
index 97758032965..d66ae606a5b 100644
--- a/apps/docs/features/docs/GuidesMdx.template.tsx
+++ b/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
diff --git a/apps/docs/lib/breadcrumbs.ts b/apps/docs/lib/breadcrumbs.ts
new file mode 100644
index 00000000000..6ca51d642bc
--- /dev/null
+++ b/apps/docs/lib/breadcrumbs.ts
@@ -0,0 +1,76 @@
+import * as NavItems from '~/components/Navigation/NavigationMenu/NavigationMenu.constants'
+
+export interface BreadcrumbItem {
+ name?: string
+ title?: string
+ url?: string
+}
+
+const SECTION_PATH_TO_KEY: Record<string, keyof typeof NavItems> = {
+ ai: 'ai',
+ api: 'api',
+ auth: 'auth',
+ contributing: 'contributing',
+ cron: 'cron',
+ database: 'database',
+ deployment: 'deployment',
+ functions: 'functions',
+ 'getting-started': 'gettingstarted',
+ graphql: 'graphql',
+ integrations: 'integrations',
+ 'local-development': 'local_development',
+ platform: 'platform',
+ queues: 'queues',
+ realtime: 'realtime',
+ resources: 'resources',
+ security: 'security',
+ 'self-hosting': 'self_hosting',
+ storage: 'storage',
+ telemetry: 'telemetry',
+}
+
+function getSectionMenu(pathname: string) {
+ const trimmed = pathname.replace(/^\/guides\/?/, '')
+ const top = trimmed.split('/')[0]
+ const key = SECTION_PATH_TO_KEY[top] ?? 'gettingstarted'
+ return (NavItems as Record<string, any>)[key]
+}
+
+function findMenuItemByUrl(
+ menu: any,
+ targetUrl: string,
+ parents: BreadcrumbItem[] = []
+): BreadcrumbItem[] | null {
+ if (menu.items) {
+ for (const item of menu.items) {
+ const result = findMenuItemByUrl(item, targetUrl, [...parents, menu])
+ if (result) return result
+ }
+ }
+ if (menu.url === targetUrl) {
+ return [...parents, menu]
+ }
+ return null
+}
+
+export function resolveBreadcrumbs(pathname: string): BreadcrumbItem[] {
+ if (pathname.startsWith('/guides/troubleshooting')) {
+ return [{ name: 'Troubleshooting', url: '/guides/troubleshooting' }]
+ }
+ if (pathname.startsWith('/guides/getting-started/ai-prompts')) {
+ return [
+ { name: 'Getting started', url: '/guides/getting-started' },
+ { name: 'AI Tools' },
+ { name: 'Prompts', url: '/guides/getting-started/ai-prompts' },
+ ]
+ }
+ if (pathname.startsWith('/guides/getting-started/ai-skills')) {
+ return [
+ { name: 'Getting started', url: '/guides/getting-started' },
+ { name: 'AI Tools' },
+ { name: 'Agent Skills', url: '/guides/getting-started/ai-skills' },
+ ]
+ }
+ const menu = getSectionMenu(pathname)
+ return findMenuItemByUrl(menu, pathname) ?? []
+}
diff --git a/apps/docs/lib/json-ld.ts b/apps/docs/lib/json-ld.ts
new file mode 100644
index 00000000000..0dc58618ce6
--- /dev/null
+++ b/apps/docs/lib/json-ld.ts
@@ -0,0 +1,45 @@
+import type { BreadcrumbItem } from '~/lib/breadcrumbs'
+import { PROD_URL } from '~/lib/constants'
+
+type JsonLdSchema = Record<string, unknown> | Record<string, unknown>[]
+
+export function serializeJsonLd(schema: JsonLdSchema): string {
+ return JSON.stringify(schema)
+ .replace(/</g, '\\u003c')
+ .replace(/>/g, '\\u003e')
+ .replace(/&/g, '\\u0026')
+}
+
+const DOCS_ROOT: BreadcrumbItem = { name: 'Docs', url: '' }
+const GUIDES_ROOT: BreadcrumbItem = { name: 'Guides', url: '/guides' }
+
+interface BreadcrumbListSchemaInput {
+ pathname: string
+ chain: BreadcrumbItem[]
+}
+
+export function breadcrumbListSchema({ pathname, chain }: BreadcrumbListSchemaInput) {
+ const fullChain: BreadcrumbItem[] = [DOCS_ROOT, GUIDES_ROOT, ...chain]
+
+ const itemListElement = fullChain.map((crumb, index) => {
+ const isLeaf = index === fullChain.length - 1
+ const name = crumb.title ?? crumb.name
+ const path = isLeaf ? pathname : crumb.url
+
+ const listItem: Record<string, unknown> = {
+ '@type': 'ListItem',
+ position: index + 1,
+ name,
+ }
+ if (path !== undefined) {
+ listItem.item = path === '' ? PROD_URL : `${PROD_URL}${path}`
+ }
+ return listItem
+ })
+
+ return {
+ '@context': 'https://schema.org',
+ '@type': 'BreadcrumbList',
+ itemListElement,
+ }
+}