Add semantic blog breadcrumbs and structured data

src/components/Breadcrumbs.tsx

@@ -12,6 +12,7 @@ import {
 type BreadcrumbsProps = {
   /** Section label (e.g., "Getting Started", "Blog") */
   section: string
+  items?: Array<{ label: string; to: string }>
   /** Optional link for the section */
   sectionTo?: string
   headings?: MarkdownHeading[]
@@ -22,6 +23,7 @@ type BreadcrumbsProps = {
 export function Breadcrumbs({
   section,
   sectionTo,
+  items,
   headings,
   tocHiddenBreakpoint = 'lg',
 }: BreadcrumbsProps) {
@@ -36,7 +38,26 @@ export function Breadcrumbs({
   return (
     <div className="flex flex-col">
       <div className="flex items-center justify-between gap-4 text-sm text-gray-500 dark:text-gray-400">
-        {sectionTo ? (
+        {items ? (
+          <nav aria-label="Breadcrumb" className="min-w-0">
+            <ol className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+              {items.map((item, index) => (
+                <li key={item.to} className="min-w-0 flex gap-2">
+                  {index > 0 && <span aria-hidden="true">/</span>}
+                  {index === items.length - 1 ? (
+                    <span aria-current="page" className="break-words">
+                      {item.label}
+                    </span>
+                  ) : (
+                    <Link to={item.to} className="hover:underline">
+                      {item.label}
+                    </Link>
+                  )}
+                </li>
+              ))}
+            </ol>
+          </nav>
+        ) : sectionTo ? (
           <Link
             to={sectionTo}
             className="whitespace-nowrap hover:text-gray-700 dark:hover:text-gray-200 transition-colors"

src/routes/blog.$.tsx

@@ -17,7 +17,11 @@ import { findMaintainerByAuthorName } from '~/utils/authors'
 import { CoverFallback } from '~/components/CoverFallback'
 import { fetchBlogPost } from '~/utils/blog.functions'
 import { parseBlogMarkdown } from '~/utils/blogMarkdown'
-import { getBlogPostHead, getBlogSocialImageUrl } from '~/utils/blog-post-seo'
+import {
+  getBlogBreadcrumbItems,
+  getBlogPostHead,
+  getBlogSocialImageUrl,
+} from '~/utils/blog-post-seo'
 
 export const Route = createFileRoute('/blog/$')({
   staleTime: Infinity,
@@ -51,6 +55,7 @@ function BlogPost() {
     published,
     filePath,
     title,
+    slug: postSlug,
     headerImage,
     headerVideo,
     headerVideoCaptions,
@@ -140,7 +145,10 @@ function BlogPost() {
                     >
                       <Breadcrumbs
                         section="Blog"
-                        sectionTo="/blog"
+                        items={getBlogBreadcrumbItems({
+                          title,
+                          slug: postSlug,
+                        })}
                         headings={isTocVisible ? headings : undefined}
                         tocHiddenBreakpoint="xl"
                       />

src/utils/blog-post-seo.ts

@@ -37,13 +37,30 @@ export function getBlogSocialImageUrl(headerImage: string | undefined) {
   })
 }
 
+export function getBlogBreadcrumbItems(post: { title: string; slug: string }) {
+  return [
+    { label: 'Blog', to: '/blog' },
+    { label: post.title, to: `/blog/${post.slug}` },
+  ]
+}
+
 export function getBlogPostingJsonLd(post: BlogPostHeadData) {
   const pageUrl = canonicalUrl(`/blog/${post.slug}`)
 
   return {
     '@context': 'https://schema.org',
     '@graph': [
       getTanStackOrganizationJsonLd(),
+      {
+        '@type': 'BreadcrumbList',
+        '@id': `${pageUrl}#breadcrumb`,
+        itemListElement: getBlogBreadcrumbItems(post).map((item, index) => ({
+          '@type': 'ListItem',
+          position: index + 1,
+          name: item.label,
+          item: canonicalUrl(item.to),
+        })),
+      },
       {
         '@type': 'BlogPosting' as const,
         '@id': `${pageUrl}#blog-post`,

tests/blog-post-seo.test.ts

@@ -8,6 +8,7 @@ import {
 } from '../src/utils/blog-format'
 import {
   type BlogPostHeadData,
+  getBlogBreadcrumbItems,
   getBlogPostHead,
   getBlogSocialImageUrl,
 } from '../src/utils/blog-post-seo'
@@ -235,3 +236,36 @@ test('known modification dates reach frontmatter, JSON-LD, and article metadata'
     true,
   )
 })
+
+test('blog breadcrumbs use the visible trail with canonical ordered URLs', () => {
+  const post = {
+    ...basePost,
+    slug: '2026/typed-routing',
+    title: 'Routing & <Types>',
+  }
+  const trail = getBlogBreadcrumbItems(post)
+  assert.deepEqual(trail, [
+    { label: 'Blog', to: '/blog' },
+    { label: post.title, to: '/blog/2026/typed-routing' },
+  ])
+  const graph = getJsonLd(getBlogPostHead(post))['@graph']
+  const breadcrumb = graph.find((node) => node['@type'] === 'BreadcrumbList')
+  assert.deepEqual(breadcrumb, {
+    '@type': 'BreadcrumbList',
+    '@id': 'https://tanstack.com/blog/2026/typed-routing#breadcrumb',
+    itemListElement: [
+      {
+        '@type': 'ListItem',
+        position: 1,
+        name: 'Blog',
+        item: 'https://tanstack.com/blog',
+      },
+      {
+        '@type': 'ListItem',
+        position: 2,
+        name: post.title,
+        item: 'https://tanstack.com/blog/2026/typed-routing',
+      },
+    ],
+  })
+})