OG & Metadata Toolkit
One helper that gives every page consistent SEO and social cards.
Builders & toolkitsLiveNext.jsnext/og
13kcards
What it is
A centralized metadata builder plus dynamic OpenGraph image generation. Every page calls one helper for canonical URLs, OG tags, Twitter cards and themed social images: consistent SEO with no boilerplate.
Take it with you
The real, committed source behind this system. Copy it or download the file. Plus a portable spec of everything on this page.
metadata.jsjavascript435 lines
The central metadata builder — canonical URLs, OpenGraph/Twitter tags and dynamic OG images from one buildMetadata() call.
// ---------------------------------------------------------------------------
// buildMetadata — centralized metadata for every page on jakelawrence.xyz
// buildEnrichedMetadata — enrichment-aware wrapper around buildMetadata
// getEnrichedJsonLd — enrichment-aware JSON-LD helper
// ---------------------------------------------------------------------------
//
// Usage (any page.jsx):
//
// import { buildMetadata } from '@/lib/metadata'
//
// export const metadata = buildMetadata({
// title: 'Stable Match',
// subtitle: 'Gale-Shapley Algorithm',
// description: 'Match partners and test for stability...',
// path: '/games/stable-match',
// })
//
// The helper handles: title (with layout template awareness), OG tags,
// Twitter Card, canonical URL, and sensible defaults for everything else.
// ---------------------------------------------------------------------------
import { getApprovedMetadata } from '@/lib/enrichments'
import { blogOgImagePath } from '@/lib/og-url'
import { BASE_URL, SITE_NAME, DEFAULT_OG_IMAGE } from '@/lib/site/constants'
import { OG_LOCALE, DEFAULT_LOCALE } from '@/lib/i18n/locales.mjs'
/**
* Infer a category from the URL path for OG image styling.
*/
function inferCategory(path) {
if (path.startsWith('/research')) return 'research'
if (path.startsWith('/novels') || path.startsWith('/the-beautiful-unfinished')) return 'novels'
if (path.startsWith('/compass/ethics')) return 'ethics'
if (path.startsWith('/compass/values')) return 'values'
if (path.startsWith('/compass')) return 'compass'
if (path.startsWith('/utilities')) return 'utilities'
if (path.startsWith('/hire')) return 'hire'
if (path.startsWith('/games')) return 'games'
const gameRoutes = [
'/dice-or-die', '/cube-dojo', '/chessguessr', '/rating-game',
'/machine-mirror', '/word-machine', '/case-cooking',
'/airway', '/prompt-mirror', '/spa-menu',
'/subgenre-survival', '/population-game',
]
if (gameRoutes.some(r => path.startsWith(r))) return 'games'
// Publishable multi-tenant boards — branded OG per add-on. Use trailing-slash
// prefixes so the board slug routes match (and /t/ never catches /trip|/tools).
if (path.startsWith('/w/')) return 'weather'
if (path.startsWith('/cd/')) return 'countdowns'
if (path.startsWith('/trip/')) return 'trips'
if (path.startsWith('/t/')) return 'todos'
return ''
}
/**
* Build consistent metadata for any page.
*
* Options:
* title — Page title (layout template appends " — Jake Lawrence")
* subtitle — Optional subtitle: "Title — Subtitle" in browser tab
* description — Meta description (keep under 155 chars)
* path — Page path starting with /
* ogImage; OG image path (defaults to dynamic theme OG via /api/og)
* ogImageAlt — Alt text for the OG image (defaults to title)
* type — 'website' (default) or 'article'
* absoluteTitle — If true, bypasses layout's " — Jake Lawrence" suffix
* locale — Content language ('en' default, 'ua' for /ua pages). Sets
* the OpenGraph locale tag.
* hreflang — Optional map of locale → canonical path (e.g.
* { en: '/research', ua: '/ua/research' }). When provided,
* emits alternates.languages (+ x-default → the en entry) so
* search engines pair the localized twins. Use hreflangMap()
* from @/lib/i18n to build it.
*/
export function buildMetadata({
title,
subtitle,
description,
path,
ogImage,
ogImageAlt,
type = 'website',
absoluteTitle = false,
keywords,
locale = DEFAULT_LOCALE,
hreflang,
}) {
const url = `${BASE_URL}${path}`
// hreflang → absolute-URL languages map, with x-default pointing at English.
const languages = hreflang
? Object.fromEntries(
Object.entries({ ...hreflang, 'x-default': hreflang['x-default'] || hreflang.en })
.filter(([, p]) => p)
.map(([k, p]) => [k, p.startsWith('http') ? p : `${BASE_URL}${p}`])
)
: undefined
// Dynamic OG image generation when no explicit ogImage provided
const category = inferCategory(path)
const dynamicOg = `/api/og?${new URLSearchParams({
title,
...(description && { subtitle: description }),
...(category && { category }),
})}`
const image = ogImage || dynamicOg
const imageUrl = image.startsWith('http') ? image : `${BASE_URL}${image}`
// Browser tab title: "Title — Subtitle" (layout template appends " — Jake Lawrence")
const tabTitle = subtitle ? `${title} \u2014 ${subtitle}` : title
// OG/Twitter title: standalone, includes site name since social cards
// don't go through the Next.js layout title template
const socialTitle = subtitle
? `${title} \u2014 ${subtitle} | ${SITE_NAME}`
: `${title} | ${SITE_NAME}`
return {
title: absoluteTitle ? { absolute: tabTitle } : tabTitle,
description,
...(keywords?.length && { keywords }),
alternates: {
canonical: url,
...(languages && { languages }),
},
openGraph: {
title: socialTitle,
description,
url,
siteName: SITE_NAME,
locale: OG_LOCALE[locale] || OG_LOCALE[DEFAULT_LOCALE],
type,
images: [
{
url: imageUrl,
width: 1200,
height: 630,
alt: ogImageAlt || tabTitle,
},
],
},
twitter: {
card: 'summary_large_image',
title: socialTitle,
description,
images: [imageUrl],
},
}
}
/**
* Build JSON-LD structured data for a WebApplication (game) page.
* Returns a JSON string to embed in a <script type="application/ld+json"> tag.
*/
export function buildGameJsonLd({ name, description, path }) {
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'WebApplication',
name,
description,
url: `${BASE_URL}${path}`,
applicationCategory: 'EducationalApplication',
operatingSystem: 'Web Browser',
author: {
'@type': 'Person',
name: SITE_NAME,
url: BASE_URL,
},
offers: {
'@type': 'Offer',
price: '0',
priceCurrency: 'USD',
},
})
}
/**
* Build JSON-LD for the podcast series (the /podcast index). Returns a JSON
* string for a <script type="application/ld+json"> tag.
*/
export function buildPodcastSeriesJsonLd({ name, description, path, image, feedPath = '/podcast/feed.xml' }) {
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'PodcastSeries',
name,
description,
url: `${BASE_URL}${path}`,
webFeed: `${BASE_URL}${feedPath}`,
...(image && { image: image.startsWith('http') ? image : `${BASE_URL}${image}` }),
author: { '@type': 'Person', name: SITE_NAME, url: BASE_URL },
})
}
/**
* Build JSON-LD for a single podcast episode + its guest (the /podcast/<slug>
* deliverable page). The guest is modeled as a Person so the share preview and
* search engines credit them by name. Returns a JSON string.
*/
export function buildPodcastEpisodeJsonLd({ name, description, path, datePublished, guest, audioUrl, transcript, seriesName = 'Between Systems', seriesPath = '/podcast' }) {
// Flatten a [{ speaker, text }] transcript to a single text block for the
// schema.org `transcript` property (helps the episode rank on its content).
const transcriptText = Array.isArray(transcript) && transcript.length
? transcript.map((s) => (s.speaker ? `${s.speaker}: ${s.text}` : s.text)).join('\n\n')
: ''
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'PodcastEpisode',
name,
description,
url: `${BASE_URL}${path}`,
...(datePublished && { datePublished }),
...(transcriptText && { transcript: transcriptText }),
partOfSeries: {
'@type': 'PodcastSeries',
name: seriesName,
url: `${BASE_URL}${seriesPath}`,
},
...(audioUrl && {
associatedMedia: { '@type': 'MediaObject', contentUrl: audioUrl },
}),
...(guest?.name && {
actor: {
'@type': 'Person',
name: guest.name,
...(guest.title && { jobTitle: guest.title }),
...(guest.org && { affiliation: { '@type': 'Organization', name: guest.org } }),
...(guest.links?.length && { sameAs: guest.links.map((l) => l.url) }),
},
}),
author: { '@type': 'Person', name: SITE_NAME, url: BASE_URL },
})
}
/**
* Build JSON-LD for a schema.org Dataset page (Google Dataset Search reads
* this markup; it is one of the few registries where this site's civic data
* can plausibly rank first). `distributionPath` should point at a real
* machine-readable download (a dataset.json route) so the entry is honest,
* not decorative. Returns a JSON string for a <script type="application/ld+json"> tag.
* Services the distribution graph's ch-google-dataset-search discovery edge.
*/
export function buildDatasetJsonLd({
name,
description,
path,
keywords = [],
dateModified,
temporalCoverage,
spatialCoverage,
distributionPath,
license,
ogImage,
}) {
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'Dataset',
name,
description,
url: `${BASE_URL}${path}`,
isAccessibleForFree: true,
...(ogImage && { image: absoluteImage(ogImage) }),
...(license && { license }),
...(keywords.length && { keywords }),
...(dateModified && { dateModified }),
...(temporalCoverage && { temporalCoverage }),
...(spatialCoverage && { spatialCoverage: { '@type': 'Place', name: spatialCoverage } }),
...(distributionPath && {
distribution: [
{
'@type': 'DataDownload',
encodingFormat: 'application/json',
contentUrl: `${BASE_URL}${distributionPath}`,
},
],
}),
creator: {
'@type': 'Person',
name: SITE_NAME,
url: BASE_URL,
},
})
}
// A JSON-LD `image` must be absolute. Callers pass the same site-relative
// path they give buildMetadata (`/api/og/research?slug=...`), or a full URL.
function absoluteImage(src) {
return /^https?:\/\//.test(src) ? src : `${BASE_URL}${src}`
}
/**
* Build JSON-LD structured data for an Article page. `ogImage` (site-relative
* or absolute) becomes the Article's `image`; about thirty research layouts
* already pass it, and until this parameter existed the argument was dropped.
*/
export function buildArticleJsonLd({ headline, description, path, wordCount, genre, ogImage }) {
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'Article',
headline,
description,
url: `${BASE_URL}${path}`,
wordCount,
...(genre && { genre }),
...(ogImage && { image: absoluteImage(ogImage) }),
author: {
'@type': 'Person',
name: SITE_NAME,
url: BASE_URL,
},
publisher: {
'@type': 'Person',
name: SITE_NAME,
},
})
}
/**
* Build BreadcrumbList JSON-LD for any page.
*/
export function buildBreadcrumbJsonLd(path) {
const segments = path.split('/').filter(Boolean)
const items = [
{ '@type': 'ListItem', position: 1, name: 'Home', item: BASE_URL },
]
let currentPath = BASE_URL
segments.forEach((segment, i) => {
currentPath += `/${segment}`
items.push({
'@type': 'ListItem',
position: i + 2,
name: segment.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
item: currentPath,
})
})
return JSON.stringify({
'@context': 'https://schema.org',
'@type': 'BreadcrumbList',
itemListElement: items,
})
}
// ---------------------------------------------------------------------------
// Enrichment-aware helpers
// ---------------------------------------------------------------------------
/**
* Build metadata using approved enrichment data when available, falling back
* to the provided hardcoded values.
*
* Usage:
* export const metadata = buildEnrichedMetadata('game-stable-match', {
* title: 'Stable Match — Gale-Shapley Algorithm',
* description: 'Match partners and test for stability...',
* path: '/games/stable-match',
* })
*/
export async function buildEnrichedMetadata(assetId, fallback) {
const enriched = await getApprovedMetadata(assetId)
if (!enriched) return buildMetadata(fallback)
return buildMetadata({
...fallback,
title: enriched.title || fallback.title,
description: enriched.description || fallback.description,
keywords: enriched.tags,
})
}
/**
* Return enriched JSON-LD string if available, otherwise the fallback string.
*
* Usage:
* <script type="application/ld+json" dangerouslySetInnerHTML={{
* __html: getEnrichedJsonLd('game-stable-match', buildGameJsonLd({...}))
* }} />
*/
export async function getEnrichedJsonLd(assetId, fallbackJsonLd) {
const enriched = await getApprovedMetadata(assetId)
if (enriched?.jsonLd) return JSON.stringify(enriched.jsonLd)
return fallbackJsonLd
}
// ---------------------------------------------------------------------------
// Blog post metadata
// ---------------------------------------------------------------------------
/**
* Build metadata for a blog post page with Discover-optimized robots directives.
*
* Pass `{ locale: 'ua' }` for the /ua/blog twin. When the post carries a
* Ukrainian translation (`post.hasUaTranslation`), both the English and the
* Ukrainian page emit hreflang alternates pairing the two.
*
* Usage:
* export async function generateMetadata({ params }) {
* const post = getBlogPostBySlug(params.slug)
* return buildBlogPostMetadata(post)
* }
*/
export function buildBlogPostMetadata(post, { locale = 'en' } = {}) {
if (!post) return buildMetadata({ title: 'Post Not Found', description: '', path: '/blog' })
const heroImage = blogOgImagePath(post)
const enPath = `/blog/${post.slug}`
const uaPath = `/ua${enPath}`
const path = locale === 'ua' ? uaPath : enPath
// Only pair the twins when a Ukrainian translation actually exists (the UA
// page always has one; the English page only when post.hasUaTranslation).
const hreflang =
locale === 'ua' || post.hasUaTranslation
? { en: enPath, ua: uaPath, 'x-default': enPath }
: undefined
return {
...buildMetadata({
title: post.title,
description: post.description,
path,
locale,
hreflang,
ogImage: heroImage,
ogImageAlt: post.heroAlt || post.title,
type: 'article',
keywords: post.tags,
}),
robots: {
index: true,
follow: true,
'max-image-preview': 'large',
'max-snippet': -1,
'max-video-preview': -1,
},
}
}
Where it lives
- src/lib/metadata.js
- src/lib/structured-data.jsx
- src/app/api/og/route.jsx
See it in action
Architecture map →FAQ
What does the toolkit cover?
Canonical URLs, OpenGraph and Twitter tags, structured-data JSON-LD, and dynamically generated themed OG images: all from a single buildMetadata helper.
Part of these stacks
Related systems
Want a system like this built for you?Work with me →