fix: omit unlinked breadcrumb crumbs from JSON-LD

app/pages/[...slug].vue

@@ -30,8 +30,8 @@
 
 const surroundLinks = computed(() => findSurroundLinks(navigation?.value, selfPath.value))
 
 const fm = computed<Record<string, any>>(() => page.value?.data ?? {})
 const tocLinks = computed<any[]>(() => (page.value?.meta as any)?.toc?.links ?? [])
 
 const title = computed(() => fm.value.seo?.title || fm.value.title)
 const description = computed(() => fm.value.seo?.description || fm.value.description)
@@ -85,19 +85,14 @@
               },
               author: { '@type': 'Organization', name: seo?.siteName, url: site.url },
             },
-            {
-              '@context': 'https://schema.org',
-              '@type': 'BreadcrumbList',
-              itemListElement: [
-                { '@type': 'ListItem', position: 1, name: 'Docs', item: site.url },
-                ...breadcrumb.value.map((item, index) => ({
-                  '@type': 'ListItem',
-                  position: index + 2,
-                  name: item.title,
-                  ...(item.path ? { item: joinURL(site.url, item.path) } : {}),
-                })),
-              ],
-            },
+            // Google requires `item` on every ListItem. Non-page section nodes
+            // (page: false) only have a title — omit them from structured data.
+            breadcrumbListLd([
+              { name: 'Docs', item: site.url },
+              ...breadcrumb.value
+                .filter((item): item is { title: string, path: string } => Boolean(item.path))
+                .map((item) => ({ name: item.title, item: joinURL(site.url, item.path) })),
+            ]),
           ])
         ),
       },

app/utils/json-ld.ts

@@ -7,3 +7,26 @@
 export function jsonLd(value: unknown): string {
   return JSON.stringify(value).replaceAll('<', '\\u003c').replaceAll('>', '\\u003e').replaceAll('&', '\\u0026')
 }
+
+export interface BreadcrumbListEntry {
+  name: string
+  /** Absolute URL. Required by Google for every BreadcrumbList ListItem. */
+  item: string
+}
+
+/**
+ * Build a schema.org BreadcrumbList. Every entry must carry an absolute `item` URL — Google rejects
+ * crumbs that only have a name (e.g. non-page section nodes in the docs nav).
+ */
+export function breadcrumbListLd(entries: BreadcrumbListEntry[]) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: entries.map((entry, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: entry.name,
+      item: entry.item,
+    })),
+  }
+}

test/og.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { truncate, withAlpha } from '../app/utils/og'
-import { jsonLd } from '../app/utils/json-ld'
+import { breadcrumbListLd, jsonLd } from '../app/utils/json-ld'
 
 describe('withAlpha', () => {
   it('expands 6-digit hex', () => {
@@ -60,3 +60,35 @@ describe('jsonLd', () => {
     expect(JSON.parse(output).name).toBe('A & B')
   })
 })
+
+describe('breadcrumbListLd', () => {
+  it('emits position + item on every ListItem (Google requires item)', () => {
+    expect(
+      breadcrumbListLd([
+        { name: 'Docs', item: 'https://comark.dev' },
+        { name: 'Introduction', item: 'https://comark.dev/getting-started/introduction' },
+      ])
+    ).toEqual({
+      '@context': 'https://schema.org',
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        { '@type': 'ListItem', position: 1, name: 'Docs', item: 'https://comark.dev' },
+        {
+          '@type': 'ListItem',
+          position: 2,
+          name: 'Introduction',
+          item: 'https://comark.dev/getting-started/introduction',
+        },
+      ],
+    })
+  })
+
+  it('never omits item, even for a single root crumb', () => {
+    const list = breadcrumbListLd([{ name: 'Docs', item: 'https://comark.dev/' }])
+    for (const entry of list.itemListElement) {
+      expect(entry).toHaveProperty('item')
+      expect(typeof entry.item).toBe('string')
+      expect(entry.item.length).toBeGreaterThan(0)
+    }
+  })
+})