Skip to content

Commit 477d87b

Browse files
Add factual document and breadcrumb structured data (#1266)
* fix: read local docs directories through the worker bridge * feat(docs): show verified freshness and tested versions * fix: allow local repository root directory reads * feat: add factual structured data to documentation pages * Share semantic docs breadcrumbs with structured data
1 parent 1fa70f8 commit 477d87b

8 files changed

Lines changed: 309 additions & 9 deletions

File tree

‎src/components/Doc.tsx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { BreadcrumbItem } from './Breadcrumbs'
12
import type { readDocsFreshness } from '~/utils/docs-freshness'
23
import * as React from 'react'
34
import {
@@ -37,6 +38,7 @@ type DocProps = {
3738
pagePath?: string
3839
// Breadcrumb props (optional)
3940
config?: ConfigSchema
41+
breadcrumbItems?: Array<BreadcrumbItem>
4042
// Footer content rendered after markdown
4143
footer?: React.ReactNode
4244
// Optional framework to use (overrides URL and local storage)
@@ -58,6 +60,7 @@ export function Doc({
5860
libraryVersion,
5961
pagePath,
6062
config,
63+
breadcrumbItems,
6164
footer,
6265
framework: frameworkProp,
6366
}: DocProps) {
@@ -161,10 +164,11 @@ export function Doc({
161164
)}
162165
>
163166
<div className="flex flex-col w-full min-w-0">
164-
{config && (
167+
{(config || breadcrumbItems) && (
165168
<div className="mb-3">
166169
<DocBreadcrumb
167170
config={config}
171+
items={breadcrumbItems}
168172
headings={isTocVisible ? headings : undefined}
169173
/>
170174
</div>

‎src/components/DocBreadcrumb.tsx‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { useParams } from '@tanstack/react-router'
2-
import { Breadcrumbs } from './Breadcrumbs'
2+
import { Breadcrumbs, type BreadcrumbItem } from './Breadcrumbs'
33
import type { ConfigSchema } from '~/utils/config'
44
import type { MarkdownHeading } from '~/utils/markdown'
55

@@ -32,9 +32,11 @@ function findSectionForDoc(
3232

3333
export function DocBreadcrumb({
3434
config,
35+
items,
3536
headings,
3637
}: {
37-
config: ConfigSchema
38+
config?: ConfigSchema
39+
items?: Array<BreadcrumbItem>
3840
headings?: MarkdownHeading[]
3941
}) {
4042
const { _splat, framework } = useParams({ strict: false })
@@ -44,16 +46,18 @@ export function DocBreadcrumb({
4446
const fullDocPath = framework ? `framework/${framework}/${_splat}` : _splat
4547

4648
// Find the section for this doc
47-
const section = fullDocPath ? findSectionForDoc(config, fullDocPath) : null
49+
const section =
50+
config && fullDocPath ? findSectionForDoc(config, fullDocPath) : null
4851

49-
// Only show if we found a section
50-
if (!section) {
52+
// Keep the section-only mode for callers without a semantic trail.
53+
if (!section && !items) {
5154
return null
5255
}
5356

5457
return (
5558
<Breadcrumbs
56-
section={section}
59+
section={section ?? ''}
60+
items={items}
5761
headings={headings}
5862
tocHiddenBreakpoint="xl"
5963
/>

‎src/routes/_library/$libraryId/$version.docs.$.tsx‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1+
import { getDocsBreadcrumbItems } from '~/utils/docs-breadcrumbs'
12
import { canonicalUrl, seo } from '~/utils/seo'
3+
import { getDocsStructuredData } from '~/utils/docs-structured-data'
24
import { ogImageUrl } from '~/utils/og'
35
import { Doc } from '~/components/Doc'
46
import {
@@ -98,7 +100,24 @@ export const Route = createFileRoute('/_library/$libraryId/$version/docs/$')({
98100
appendPathToDocsHref({ docsPath: docsPath ?? '', libraryId, version }),
99101
)
100102

103+
const structuredData = getDocsStructuredData({
104+
doc: loaderData,
105+
library,
106+
canonicalHref,
107+
})
108+
101109
return {
110+
scripts: structuredData
111+
? [
112+
{
113+
type: 'application/ld+json',
114+
children: JSON.stringify(structuredData).replaceAll(
115+
'<',
116+
'\\u003c',
117+
),
118+
},
119+
]
120+
: [],
102121
meta: [
103122
...seo({
104123
title: loaderData?.title
@@ -138,7 +157,8 @@ export const Route = createFileRoute('/_library/$libraryId/$version/docs/$')({
138157

139158
function Docs() {
140159
const { version, libraryId, _splat } = Route.useParams()
141-
const { content, filePath, title, freshness } = Route.useLoaderData()
160+
const { content, filePath, title, freshness, canonicalPathOverride } =
161+
Route.useLoaderData()
142162
const versionMatch = useMatch({ from: '/_library/$libraryId/$version' })
143163
const config = versionMatch.loaderData?.config
144164
const library = getLibrary(libraryId)
@@ -149,6 +169,13 @@ function Docs() {
149169
<DocContainer>
150170
<Doc
151171
title={title}
172+
breadcrumbItems={getDocsBreadcrumbItems({
173+
doc: { title },
174+
library,
175+
canonicalHref: canonicalUrl(
176+
canonicalPathOverride ?? location.pathname,
177+
),
178+
})}
152179
freshness={freshness}
153180
content={content}
154181
repo={library.repo}

‎src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { getDocsBreadcrumbItems } from '~/utils/docs-breadcrumbs'
12
import {
23
notFound,
34
redirect,
@@ -6,6 +7,7 @@ import {
67
createFileRoute,
78
} from '@tanstack/react-router'
89
import { canonicalUrl, seo } from '~/utils/seo'
10+
import { getDocsStructuredData } from '~/utils/docs-structured-data'
911
import { ogImageUrl } from '~/utils/og'
1012
import { Doc } from '~/components/Doc'
1113
import {
@@ -110,7 +112,24 @@ export const Route = createFileRoute(
110112
}),
111113
)
112114

115+
const structuredData = getDocsStructuredData({
116+
doc: ctx.loaderData,
117+
library,
118+
canonicalHref,
119+
})
120+
113121
return {
122+
scripts: structuredData
123+
? [
124+
{
125+
type: 'application/ld+json',
126+
children: JSON.stringify(structuredData).replaceAll(
127+
'<',
128+
'\\u003c',
129+
),
130+
},
131+
]
132+
: [],
114133
meta: [
115134
...seo({
116135
title: ctx.loaderData?.title
@@ -133,7 +152,8 @@ export const Route = createFileRoute(
133152
})
134153

135154
function Docs() {
136-
const { content, filePath, title, freshness } = Route.useLoaderData()
155+
const { content, filePath, title, freshness, canonicalPathOverride } =
156+
Route.useLoaderData()
137157
const versionMatch = useMatch({ from: '/_library/$libraryId/$version' })
138158
const config = versionMatch.loaderData?.config
139159
const { version, libraryId, framework } = Route.useParams()
@@ -146,6 +166,13 @@ function Docs() {
146166
<Doc
147167
key={filePath}
148168
title={title}
169+
breadcrumbItems={getDocsBreadcrumbItems({
170+
doc: { title },
171+
library,
172+
canonicalHref: canonicalUrl(
173+
canonicalPathOverride ?? location.pathname,
174+
),
175+
})}
149176
freshness={freshness}
150177
content={content}
151178
repo={library.repo}

‎src/utils/docs-breadcrumbs.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import type { BreadcrumbItem } from '~/components/Breadcrumbs'
2+
3+
export function getDocsBreadcrumbItems({
4+
doc,
5+
library,
6+
canonicalHref,
7+
}: {
8+
doc: { title: string } | undefined
9+
library: { id: string; name: string; visible?: boolean }
10+
canonicalHref: string
11+
}): Array<BreadcrumbItem> | undefined {
12+
if (!doc?.title || library.visible === false) return undefined
13+
return [
14+
{ label: 'Libraries', to: '/libraries' },
15+
{ label: library.name, to: `/${library.id}/latest` },
16+
{ label: doc.title, to: canonicalHref },
17+
]
18+
}

‎src/utils/docs-structured-data.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import { getDocsBreadcrumbItems } from './docs-breadcrumbs'
2+
import type { readDocsFreshness } from './docs-freshness'
3+
import {
4+
getTanStackOrganizationJsonLd,
5+
TANSTACK_ORGANIZATION_ID,
6+
} from './organization-structured-data'
7+
8+
export function getDocsStructuredData({
9+
doc,
10+
library,
11+
canonicalHref,
12+
}: {
13+
doc:
14+
| {
15+
title: string
16+
description?: string
17+
freshness?: ReturnType<typeof readDocsFreshness>
18+
}
19+
| undefined
20+
library: { id: string; name: string; visible?: boolean }
21+
canonicalHref: string
22+
}) {
23+
const items = getDocsBreadcrumbItems({ doc, library, canonicalHref })
24+
if (!doc?.title || !items) return undefined
25+
26+
return {
27+
'@context': 'https://schema.org',
28+
'@graph': [
29+
getTanStackOrganizationJsonLd(),
30+
{
31+
'@type': 'WebPage',
32+
'@id': canonicalHref,
33+
url: canonicalHref,
34+
name: doc.title,
35+
...(doc.description ? { description: doc.description } : {}),
36+
breadcrumb: { '@id': `${canonicalHref}#breadcrumb` },
37+
mainEntity: { '@id': `${canonicalHref}#article` },
38+
},
39+
{
40+
'@type': 'TechArticle',
41+
'@id': `${canonicalHref}#article`,
42+
headline: doc.title,
43+
...(doc.description ? { description: doc.description } : {}),
44+
mainEntityOfPage: { '@id': canonicalHref },
45+
publisher: { '@id': TANSTACK_ORGANIZATION_ID },
46+
...(doc.freshness?.updated
47+
? { dateModified: doc.freshness.updated }
48+
: {}),
49+
},
50+
{
51+
'@type': 'BreadcrumbList',
52+
'@id': `${canonicalHref}#breadcrumb`,
53+
itemListElement: items.map((item, index) => ({
54+
'@type': 'ListItem',
55+
position: index + 1,
56+
name: item.label,
57+
item: new URL(item.to, canonicalHref).href,
58+
})),
59+
},
60+
],
61+
}
62+
}

‎tests/docs-breadcrumbs.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import assert from 'node:assert/strict'
2+
import { test } from 'node:test'
3+
import { getDocsBreadcrumbItems } from '../src/utils/docs-breadcrumbs'
4+
import { getDocsStructuredData } from '../src/utils/docs-structured-data'
5+
6+
test('visible and schema trails share labels, ordering and canonical destinations', () => {
7+
for (const canonicalHref of [
8+
'https://tanstack.com/query/latest/docs/framework/react/guides/query-keys',
9+
'https://tanstack.com/query/v3/docs/overview',
10+
]) {
11+
const input = {
12+
doc: { title: 'Query keys <script>' },
13+
library: { id: 'query', name: 'TanStack Query' },
14+
canonicalHref,
15+
}
16+
const items = getDocsBreadcrumbItems(input)
17+
const schema = getDocsStructuredData(input)?.['@graph'].find(
18+
(node) => node['@type'] === 'BreadcrumbList',
19+
)
20+
assert.ok(items)
21+
assert.ok(schema && 'itemListElement' in schema)
22+
assert.equal(items.length, 3)
23+
assert.equal(items.at(-1)?.label, input.doc.title)
24+
assert.equal(items.at(-1)?.to, canonicalHref)
25+
assert.deepEqual(
26+
schema.itemListElement,
27+
items.map((item, index) => ({
28+
'@type': 'ListItem',
29+
position: index + 1,
30+
name: item.label,
31+
item: new URL(item.to, canonicalHref).href,
32+
})),
33+
)
34+
}
35+
})
36+
37+
test('hidden, missing and untitled documents have no semantic trail', () => {
38+
const input = {
39+
library: { id: 'workflow', name: 'Workflow', visible: false },
40+
canonicalHref: 'https://tanstack.com/workflow/latest/docs/overview',
41+
}
42+
assert.equal(
43+
getDocsBreadcrumbItems({ ...input, doc: { title: 'Overview' } }),
44+
undefined,
45+
)
46+
assert.equal(
47+
getDocsBreadcrumbItems({
48+
...input,
49+
library: { ...input.library, visible: true },
50+
doc: undefined,
51+
}),
52+
undefined,
53+
)
54+
assert.equal(
55+
getDocsBreadcrumbItems({
56+
...input,
57+
library: { ...input.library, visible: true },
58+
doc: { title: '' },
59+
}),
60+
undefined,
61+
)
62+
})

0 commit comments

Comments
 (0)