Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(docs) - add TechArticle JSON+LD markup to /guides pages (#51497)

Kody Jackson3bd3410053b2
diff --git a/apps/docs/features/docs/GuidesMdx.template.tsx b/apps/docs/features/docs/GuidesMdx.template.tsx
index c02f8c11414..da1ec74e4b6 100644
--- a/apps/docs/features/docs/GuidesMdx.template.tsx
+++ b/apps/docs/features/docs/GuidesMdx.template.tsx
@@ -4,8 +4,9 @@ import { TocAnchorsProvider } from '~/features/docs/GuidesMdx.client'
import { MDXRemoteBase } from '~/features/docs/MdxBase'
import type { WithRequired } from '~/features/helpers.types'
import { resolveBreadcrumbs } from '~/lib/breadcrumbs'
+import { PROD_URL } from '~/lib/constants'
import { type GuideFrontmatter } from '~/lib/docs'
-import { breadcrumbListSchema, serializeJsonLd } from '~/lib/json-ld'
+import { breadcrumbListSchema, serializeJsonLd, techArticleSchema } from '~/lib/json-ld'
import { mdToPlainText } from '~/lib/md-to-plain-text'
import { SerializeOptions } from '~/types/next-mdx-remote-serialize'
import { ExternalLink } from 'lucide-react'
@@ -74,6 +75,15 @@ const GuideTemplate = ({
const breadcrumbChain = resolveBreadcrumbs(pathname)
const breadcrumbSchema = breadcrumbListSchema({ pathname, chain: breadcrumbChain })
const breadcrumbJsonLd = breadcrumbSchema ? serializeJsonLd(breadcrumbSchema) : null
+ const techArticleJsonLd = meta
+ ? serializeJsonLd(
+ techArticleSchema({
+ url: `${PROD_URL}${pathname}`,
+ headline: mdToPlainText(meta.title),
+ description: mdToPlainText(meta.description ?? meta.subtitle ?? '') || undefined,
+ })
+ )
+ : null
return (
<TocAnchorsProvider>
@@ -86,6 +96,12 @@ const GuideTemplate = ({
'col-span-12 md:col-span-8'
)}
>
+ {techArticleJsonLd && (
+ <script
+ type="application/ld+json"
+ dangerouslySetInnerHTML={{ __html: techArticleJsonLd }}
+ />
+ )}
{breadcrumbJsonLd && (
<script
type="application/ld+json"
diff --git a/apps/docs/lib/json-ld.test.ts b/apps/docs/lib/json-ld.test.ts
index 08e9a56a084..a21bcf4beb7 100644
--- a/apps/docs/lib/json-ld.test.ts
+++ b/apps/docs/lib/json-ld.test.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { breadcrumbListSchema } from './json-ld'
+import { breadcrumbListSchema, techArticleSchema } from './json-ld'
describe('breadcrumbListSchema', () => {
let warn: ReturnType<typeof vi.spyOn>
@@ -23,7 +23,7 @@ describe('breadcrumbListSchema', () => {
})
expect(result).not.toBeNull()
- expect(result!.itemListElement).toHaveLength(4)
+ expect(result!.itemListElement).toHaveLength(3)
for (const entry of result!.itemListElement) {
expect(typeof entry.item).toBe('string')
expect(entry.item).toMatch(/^https?:\/\//)
@@ -57,3 +57,47 @@ describe('breadcrumbListSchema', () => {
expect(result).toBeNull()
})
})
+
+describe('techArticleSchema', () => {
+ const url = 'https://supabase.com/docs/guides/auth/jwts'
+
+ it('describes the guide as a TechArticle on its own URL', () => {
+ const schema = techArticleSchema({
+ url,
+ headline: 'JWTs',
+ description: 'How JSON Web Tokens work.',
+ })
+
+ expect(schema['@context']).toBe('https://schema.org')
+ expect(schema['@type']).toBe('TechArticle')
+ expect(schema['@id']).toBe(`${url}#page`)
+ expect(schema.mainEntityOfPage).toEqual({ '@type': 'WebPage', '@id': url })
+ expect(schema.url).toBe(url)
+ expect(schema.headline).toBe('JWTs')
+ expect(schema.description).toBe('How JSON Web Tokens work.')
+ expect(schema.inLanguage).toBe('en')
+ })
+
+ it('omits description when none is given', () => {
+ const schema = techArticleSchema({ url, headline: 'JWTs' })
+
+ expect(schema.description).toBeUndefined()
+ })
+
+ it('omits date fields', () => {
+ const schema = techArticleSchema({ url, headline: 'JWTs' })
+
+ expect(schema).not.toHaveProperty('datePublished')
+ expect(schema).not.toHaveProperty('dateModified')
+ })
+
+ it('publishes under an inline Supabase organization', () => {
+ const schema = techArticleSchema({ url, headline: 'JWTs' })
+
+ expect(schema.publisher).toMatchObject({
+ '@type': 'Organization',
+ name: 'Supabase',
+ url: 'https://supabase.com',
+ })
+ })
+})
diff --git a/apps/docs/lib/json-ld.ts b/apps/docs/lib/json-ld.ts
index 839fd92b49c..78476f82ff0 100644
--- a/apps/docs/lib/json-ld.ts
+++ b/apps/docs/lib/json-ld.ts
@@ -13,7 +13,6 @@ export function serializeJsonLd(schema: JsonLdSchema): string {
type ValidCrumb = BreadcrumbItem & { url: string }
const DOCS_ROOT: ValidCrumb = { name: 'Docs', url: '' }
-const GUIDES_ROOT: ValidCrumb = { name: 'Guides', url: '/guides' }
interface BreadcrumbListSchemaInput {
pathname: string
@@ -45,7 +44,7 @@ export function breadcrumbListSchema({ pathname, chain }: BreadcrumbListSchemaIn
if (filteredChain.length === 0) return null
- const fullChain: ValidCrumb[] = [DOCS_ROOT, GUIDES_ROOT, ...filteredChain]
+ const fullChain: ValidCrumb[] = [DOCS_ROOT, ...filteredChain]
const itemListElement = fullChain.map((crumb, index) => {
const isLeaf = index === fullChain.length - 1
@@ -66,3 +65,36 @@ export function breadcrumbListSchema({ pathname, chain }: BreadcrumbListSchemaIn
itemListElement,
}
}
+
+const PUBLISHER = {
+ '@type': 'Organization',
+ name: 'Supabase',
+ url: 'https://supabase.com',
+ logo: {
+ '@type': 'ImageObject',
+ url: 'https://supabase.com/images/og/supabase-og.png',
+ },
+}
+
+interface TechArticleSchemaInput {
+ url: string
+ headline: string
+ description?: string
+}
+
+export function techArticleSchema({ url, headline, description }: TechArticleSchemaInput) {
+ return {
+ '@context': 'https://schema.org',
+ '@type': 'TechArticle',
+ '@id': `${url}#page`,
+ mainEntityOfPage: {
+ '@type': 'WebPage',
+ '@id': url,
+ },
+ url,
+ headline,
+ description,
+ inLanguage: 'en',
+ publisher: PUBLISHER,
+ }
+}