Add docs JSON-LD metadata

src/components/DocsJsonLd.test.tsx

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { createDocsJsonLdSchema, serializeJsonLd } from './DocsJsonLd'
+
+function techArticle(schema: ReturnType<typeof createDocsJsonLdSchema>) {
+  const article = schema['@graph'].find((entry) => entry['@type'] === 'TechArticle')
+  if (!article) throw new Error('TechArticle schema is missing')
+  return article
+}
+
+describe('DocsJsonLd', () => {
+  it.each([
+    ['/docs', 'https://docs.tempo.xyz/docs'],
+    ['docs/api', 'https://docs.tempo.xyz/docs/api'],
+    ['/docs/quickstart/integrate-tempo', 'https://docs.tempo.xyz/docs/quickstart/integrate-tempo'],
+  ])('uses the page path in TechArticle URLs', (path, url) => {
+    const article = techArticle(createDocsJsonLdSchema({ path }))
+
+    expect(article).toMatchObject({
+      '@id': url,
+      url,
+    })
+  })
+
+  it('escapes JSON-LD before injecting into a script tag', () => {
+    const json = serializeJsonLd(
+      createDocsJsonLdSchema({
+        path: '</script><script>alert(1)</script>',
+      }),
+    )
+
+    expect(json).not.toContain('</script>')
+    expect(json).toContain('\\u003c/script\\u003e')
+    expect(json).toContain('\\u003e')
+  })
+})

src/components/DocsJsonLd.tsx

@@ -0,0 +1,89 @@
+import { useRouter } from 'vocs'
+
+const tempoSameAs = [
+  'https://x.com/tempo',
+  'https://twitter.com/tempo',
+  'https://github.com/tempoxyz',
+  'https://www.linkedin.com/company/tempoxyz',
+  'https://www.crunchbase.com/organization/tempo-87e4',
+]
+
+const tempoKnowsAbout = [
+  'stablecoin payments',
+  'cross-border payments',
+  'global payouts',
+  'agentic payments',
+  'machine payments',
+  'enterprise settlement',
+  'payment blockchains',
+  'Layer 1 blockchain',
+  'stablecoin infrastructure',
+]
+
+const description =
+  'Tempo is a payments-first Layer 1 blockchain incubated by Stripe and Paradigm. Tempo documentation covers stablecoin payments, global payouts, agentic payments, APIs, wallets, and protocol specifications.'
+
+type DocsJsonLdOptions = {
+  path?: string
+}
+
+export function createDocsJsonLdSchema(options: DocsJsonLdOptions = {}) {
+  const path = options.path || '/docs'
+  const pathname = path.startsWith('/') ? path : `/${path}`
+  const url = `https://docs.tempo.xyz${pathname}`
+
+  return {
+    '@context': 'https://schema.org',
+    '@graph': [
+      {
+        '@type': 'Organization',
+        '@id': 'https://tempo.xyz/#organization',
+        name: 'Tempo',
+        url: 'https://tempo.xyz',
+        description,
+        sameAs: tempoSameAs,
+        knowsAbout: tempoKnowsAbout,
+      },
+      {
+        '@type': 'WebSite',
+        '@id': 'https://docs.tempo.xyz/#website',
+        name: 'Tempo Docs',
+        url: 'https://docs.tempo.xyz',
+        description,
+        publisher: { '@id': 'https://tempo.xyz/#organization' },
+      },
+      {
+        '@type': 'TechArticle',
+        '@id': url,
+        url,
+        headline: 'Tempo documentation',
+        description,
+        isPartOf: { '@id': 'https://docs.tempo.xyz/#website' },
+        about: { '@id': 'https://tempo.xyz/#organization' },
+        publisher: { '@id': 'https://tempo.xyz/#organization' },
+      },
+    ],
+  }
+}
+
+export function serializeJsonLd(schema: unknown) {
+  return JSON.stringify(schema)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+}
+
+export default function DocsJsonLd(props: { path?: string }) {
+  const { path } = useRouter()
+  const schema = createDocsJsonLdSchema({
+    path: props.path ?? path,
+  })
+
+  return (
+    <script
+      type="application/ld+json"
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: JSON-LD requires innerHTML; content is escaped above.
+      dangerouslySetInnerHTML={{ __html: serializeJsonLd(schema) }}
+    />
+  )
+}

src/pages/docs/_layout.tsx

@@ -2,6 +2,7 @@
 
 import { lazy, type PropsWithChildren, Suspense } from 'react'
 import DocsHeader from '../../components/DocsHeader'
+import DocsJsonLd from '../../components/DocsJsonLd'
 import DocsSectionNav from '../../components/DocsSectionNav'
 import DocsSidebarDrawer from '../../components/DocsSidebarDrawer'
 import { usePageSettled } from '../../lib/pageSettled'
@@ -41,7 +42,7 @@ if (typeof window !== 'undefined') {
 
 export default function DocsLayout(
   props: PropsWithChildren<{
-    path: string
+    path?: string
     frontmatter?: { interactive?: boolean; mipd?: boolean }
   }>,
 ) {
@@ -50,6 +51,7 @@ export default function DocsLayout(
 
   return (
     <>
+      <DocsJsonLd path={props.path} />
       <DocsHeader />
       <DocsSectionNav />
       <DocsSidebarDrawer />