Add breadcrumbs to public library landing pages

src/components/LibraryLayout.tsx

@@ -1,3 +1,5 @@
+import { Breadcrumbs } from './Breadcrumbs'
+import { getLibraryBreadcrumbItems } from '~/utils/library-breadcrumbs'
 import * as React from 'react'
 import { CaretLeftIcon } from '@phosphor-icons/react/CaretLeft'
 import { CaretRightIcon } from '@phosphor-icons/react/CaretRight'
@@ -816,6 +818,10 @@ export function LibraryLayout({
   const { _splat, version: routeVersion } = useParams({ strict: false })
   const matches = useMatches()
   const lastMatch = last(matches)
+  const landingBreadcrumbItems =
+    lastMatch.status === 'success' && lastMatch.routeId.endsWith('/$version/')
+      ? getLibraryBreadcrumbItems(getLibrary(libraryId))
+      : undefined
   const version = getLibraryLayoutVersion({
     layoutVersion,
     pathname: lastMatch.pathname,
@@ -1545,6 +1551,14 @@ export function LibraryLayout({
                     'mx-auto w-[var(--docs-content-width,900px)]',
                 )}
               >
+                {landingBreadcrumbItems && (
+                  <div className="px-4 pt-4 md:px-8">
+                    <Breadcrumbs
+                      section="Libraries"
+                      items={landingBreadcrumbItems}
+                    />
+                  </div>
+                )}
                 {children}
               </div>
             </div>

src/routes/-library-landing-route.tsx

@@ -1,3 +1,4 @@
+import { getLibraryBreadcrumbJsonLd } from '~/utils/library-breadcrumbs'
 import { redirect } from '@tanstack/react-router'
 import type { QueryClient } from '@tanstack/react-query'
 import { getLibrary } from '~/libraries'
@@ -59,10 +60,22 @@ export async function loadLibraryLandingRouteData(
   }
 }
 
-export function getLibraryLandingHead(libraryId: LandingLibraryId) {
+export function getLibraryLandingHead(
+  libraryId: LandingLibraryId,
+  isSuccess: boolean,
+) {
   const library = getLibrary(libraryId)
+  const breadcrumb = isSuccess ? getLibraryBreadcrumbJsonLd(library) : undefined
 
   return {
+    scripts: breadcrumb
+      ? [
+          {
+            type: 'application/ld+json',
+            children: JSON.stringify(breadcrumb).replaceAll('<', '\\u003c'),
+          },
+        ]
+      : [],
     meta: seo({
       title:
         libraryId === 'start'

src/routes/_library/ai.$version.index.tsx

@@ -15,7 +15,7 @@ export const Route = createFileRoute('/_library/ai/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('ai', params.version, queryClient),
-  head: () => getLibraryLandingHead('ai'),
+  head: ({ match }) => getLibraryLandingHead('ai', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('ai'),
   component: AiLandingRoute,
 })

src/routes/_library/charts.$version.index.tsx

@@ -28,7 +28,8 @@ export const Route = createFileRoute('/_library/charts/$version/')({
 
     return { ...landingData, catalogOrderSeed, catalog }
   },
-  head: () => getLibraryLandingHead('charts'),
+  head: ({ match }) =>
+    getLibraryLandingHead('charts', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('charts'),
   component: ChartsLandingRoute,
 })

src/routes/_library/cli.$version.index.tsx

@@ -15,7 +15,7 @@ export const Route = createFileRoute('/_library/cli/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('cli', params.version, queryClient),
-  head: () => getLibraryLandingHead('cli'),
+  head: ({ match }) => getLibraryLandingHead('cli', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('cli'),
   component: CliLandingRoute,
 })

src/routes/_library/config.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/config/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('config', params.version, queryClient),
-  head: () => getLibraryLandingHead('config'),
+  head: ({ match }) =>
+    getLibraryLandingHead('config', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('config'),
   component: ConfigLandingRoute,
 })

src/routes/_library/db.$version.index.tsx

@@ -15,7 +15,7 @@ export const Route = createFileRoute('/_library/db/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('db', params.version, queryClient),
-  head: () => getLibraryLandingHead('db'),
+  head: ({ match }) => getLibraryLandingHead('db', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('db'),
   component: DbLandingRoute,
 })

src/routes/_library/devtools.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/devtools/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('devtools', params.version, queryClient),
-  head: () => getLibraryLandingHead('devtools'),
+  head: ({ match }) =>
+    getLibraryLandingHead('devtools', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('devtools'),
   component: DevtoolsLandingRoute,
 })

src/routes/_library/form.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/form/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('form', params.version, queryClient),
-  head: () => getLibraryLandingHead('form'),
+  head: ({ match }) =>
+    getLibraryLandingHead('form', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('form'),
   component: FormLandingRoute,
 })

src/routes/_library/highlight.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/highlight/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('highlight', params.version, queryClient),
-  head: () => getLibraryLandingHead('highlight'),
+  head: ({ match }) =>
+    getLibraryLandingHead('highlight', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('highlight'),
   component: HighlightLandingRoute,
 })

src/routes/_library/hotkeys.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/hotkeys/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('hotkeys', params.version, queryClient),
-  head: () => getLibraryLandingHead('hotkeys'),
+  head: ({ match }) =>
+    getLibraryLandingHead('hotkeys', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('hotkeys'),
   component: HotkeysLandingRoute,
 })

src/routes/_library/intent.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/intent/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('intent', params.version, queryClient),
-  head: () => getLibraryLandingHead('intent'),
+  head: ({ match }) =>
+    getLibraryLandingHead('intent', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('intent'),
   component: IntentLandingRoute,
 })

src/routes/_library/markdown.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/markdown/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('markdown', params.version, queryClient),
-  head: () => getLibraryLandingHead('markdown'),
+  head: ({ match }) =>
+    getLibraryLandingHead('markdown', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('markdown'),
   component: MarkdownLandingRoute,
 })

src/routes/_library/pacer.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/pacer/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('pacer', params.version, queryClient),
-  head: () => getLibraryLandingHead('pacer'),
+  head: ({ match }) =>
+    getLibraryLandingHead('pacer', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('pacer'),
   component: PacerLandingRoute,
 })

src/routes/_library/query.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/query/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('query', params.version, queryClient),
-  head: () => getLibraryLandingHead('query'),
+  head: ({ match }) =>
+    getLibraryLandingHead('query', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('query'),
   component: QueryLandingRoute,
 })

src/routes/_library/ranger.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/ranger/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('ranger', params.version, queryClient),
-  head: () => getLibraryLandingHead('ranger'),
+  head: ({ match }) =>
+    getLibraryLandingHead('ranger', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('ranger'),
   component: RangerLandingRoute,
 })

src/routes/_library/redact.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/redact/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('redact', params.version, queryClient),
-  head: () => getLibraryLandingHead('redact'),
+  head: ({ match }) =>
+    getLibraryLandingHead('redact', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('redact'),
   component: RedactLandingRoute,
 })

src/routes/_library/router.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/router/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('router', params.version, queryClient),
-  head: () => getLibraryLandingHead('router'),
+  head: ({ match }) =>
+    getLibraryLandingHead('router', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('router'),
   component: RouterLandingRoute,
 })

src/routes/_library/start.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/start/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('start', params.version, queryClient),
-  head: () => getLibraryLandingHead('start'),
+  head: ({ match }) =>
+    getLibraryLandingHead('start', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('start'),
   component: StartLandingRoute,
 })

src/routes/_library/store.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/store/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('store', params.version, queryClient),
-  head: () => getLibraryLandingHead('store'),
+  head: ({ match }) =>
+    getLibraryLandingHead('store', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('store'),
   component: StoreLandingRoute,
 })

src/routes/_library/table.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/table/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('table', params.version, queryClient),
-  head: () => getLibraryLandingHead('table'),
+  head: ({ match }) =>
+    getLibraryLandingHead('table', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('table'),
   component: TableLandingRoute,
 })

src/routes/_library/virtual.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/virtual/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('virtual', params.version, queryClient),
-  head: () => getLibraryLandingHead('virtual'),
+  head: ({ match }) =>
+    getLibraryLandingHead('virtual', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('virtual'),
   component: VirtualLandingRoute,
 })

src/routes/_library/workflow.$version.index.tsx

@@ -15,7 +15,8 @@ export const Route = createFileRoute('/_library/workflow/$version/')({
   },
   loader: ({ params, context: { queryClient } }) =>
     loadLibraryLandingRouteData('workflow', params.version, queryClient),
-  head: () => getLibraryLandingHead('workflow'),
+  head: ({ match }) =>
+    getLibraryLandingHead('workflow', match.status === 'success'),
   headers: () => getLibraryLandingHeaders('workflow'),
   component: WorkflowLandingRoute,
 })

src/utils/library-breadcrumbs.ts

@@ -0,0 +1,29 @@
+import type { BreadcrumbItem } from '~/components/Breadcrumbs'
+import { canonicalUrl } from './seo'
+
+type LibraryBreadcrumbData = { name: string; to?: string; visible?: boolean }
+
+export function getLibraryBreadcrumbItems(
+  library: LibraryBreadcrumbData,
+): Array<BreadcrumbItem> | undefined {
+  if (library.visible === false || !library.to) return undefined
+  return [
+    { label: 'Libraries', to: '/libraries' },
+    { label: library.name, to: library.to },
+  ]
+}
+
+export function getLibraryBreadcrumbJsonLd(library: LibraryBreadcrumbData) {
+  const items = getLibraryBreadcrumbItems(library)
+  if (!items) return undefined
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.label,
+      item: canonicalUrl(item.to),
+    })),
+  }
+}

tests/library-breadcrumbs.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { query, workflow } from '../src/libraries'
+import {
+  getLibraryBreadcrumbItems,
+  getLibraryBreadcrumbJsonLd,
+} from '../src/utils/library-breadcrumbs'
+Object.assign(globalThis, { __TANSTACK_SITE_URL__: 'https://tanstack.com' })
+
+test('public library landing trail shares labels and canonical destinations', () => {
+  assert.deepEqual(getLibraryBreadcrumbItems(query), [
+    { label: 'Libraries', to: '/libraries' },
+    { label: 'TanStack Query', to: '/query/latest' },
+  ])
+  assert.deepEqual(getLibraryBreadcrumbJsonLd(query)?.itemListElement, [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Libraries',
+      item: 'https://tanstack.com/libraries',
+    },
+    {
+      '@type': 'ListItem',
+      position: 2,
+      name: 'TanStack Query',
+      item: 'https://tanstack.com/query/latest',
+    },
+  ])
+})
+test('hidden library emits neither a visible trail nor structured data', () => {
+  assert.equal(getLibraryBreadcrumbItems(workflow), undefined)
+  assert.equal(getLibraryBreadcrumbJsonLd(workflow), undefined)
+})
+
+test('library without a landing destination has no breadcrumb trail', () => {
+  assert.equal(
+    getLibraryBreadcrumbItems({ name: 'Unlinked library' }),
+    undefined,
+  )
+  assert.equal(
+    getLibraryBreadcrumbJsonLd({ name: 'Unlinked library' }),
+    undefined,
+  )
+})