The SEO system

Every route's head comes from one function, seoRoute() in src/lib/seo/route.ts. It returns the route's complete Next.js metadata and the JSON-LD nodes for its kind, and it writes every field every time. Next.js merges metadata shallowly: a field a route leaves out is inherited from a layout, and a partial openGraph object replaces the parent's whole one. Before this system, the root layout's canonical of / was inherited by every page on the site.

import JsonLd from '@/lib/seo/JsonLd';
import { seoRoute } from '@/lib/seo/route';

const route = seoRoute({
  path: '/handbook/design',
  title: 'Design system',
  section: 'Handbook',
  kind: 'article',
  description: 'The design canon: the four-color system, the line law, rails and seams, the doubled line and motion.',
  markdown: '/handbook/design.md',
});

export const metadata = route.metadata;

export default function Page() {
  return <JsonLd nodes={route.jsonLd} />;
}

A dynamic route calls it in generateMetadata and again in the page body with the same input.

What one call writesCopy Anchor Link

• The title: <title>, <section>, Prototemplate, dropping the section and then the site name when the result passes 60 characters. The home page is Prototemplate.
• The description: 50 to 160 characters, the length a search snippet shows whole.
• The canonical: an absolute URL from the policy below.
• Robots: index, follow with large image previews, or noindex, follow.
• Open Graph and the X card: the title, the description, the canonical as og:url, the card with its size and alt text, twitter:site @generaltxn and twitter:creator @kevskgs.
• The icon: the Prototemplate mark on the hub, the GT mark on the /d/ pages and the presenter.
• The Markdown alternate, when the page has a twin, and an RSS alternate where a page names a feed.

The policyCopy Anchor Link

policyFor(path) in src/lib/seo/policy.ts is a pure function from a pathname to whether the page is indexed, its canonical and whether the sitemap lists it.

• One canonical host. www.prototemplate.com is canonical. The two aliases serve the same deployment, and the absolute canonical in every head consolidates them without a redirect.
• Mirrors point at the original. A mirror page carries the same copy as its live page, and GT's domain is the one that should rank for it. The mirror stays crawlable, because a crawler must read a page to honor its canonical.
• Explorations stay out of results. A direction reassembles GT's copy, prices and legal text into a design study. Indexed, it would put stale claims under GT's name on another domain. src/app/d/layout.tsx gives the whole folder noindex, follow.
• Posts point at GT. The three posts are the files generaltranslation.com publishes.
• robots.txt never carries the policy. A disallowed URL can still be indexed from links, and the crawler never reads its noindex. robots.txt allows every agent and names the sitemap.

The social cardCopy Anchor Link

/og?v=&t=&s=&d=&k=&p= (src/app/og/route.tsx) draws a 1200 by 630 PNG with next/og from the query: the version, the title, the section, the description, the kind and the path. The renderer reads TTF only and applies no variable axes, so pnpm build:inter cuts two static instances from the self-hosted InterVariable into src/app/og/: weight 500 for the title and labels, weight 400 for the text. The card is a pure function of its query, so it is cached for a year, and OG_VERSION changes when the design does.

Structured dataCopy Anchor Link

Every page carries the WebSite node from the root layout. A page adds a BreadcrumbList; an article (a docs page or a handbook document) adds a TechArticle; a skill adds a TechArticle and a SoftwareSourceCode for its folder; a post adds a BlogPosting with GT's URL. serializeJsonLd escapes every block so no text can close the script tag early.

The sitemapCopy Anchor Link

src/app/sitemap.ts lists the indexable pages: a short list of singleton routes, every page src/lib/updated.ts dates, and the handbook documents and archive entries, each filtered through the policy. A page's lastmod is the date of its last commit, from updated.ts, and is left out where there is none, since a build date tells a crawler nothing. A new indexable page gets an entry in scripts/build/updated.mjs.

The agent filesCopy Anchor Link

The twins are prerendered and never rendered on demand. Each docs page also links /llms.txt with rel="describedby" in its head and carries one machine-only llms.txt link that readers never see.

The lintCopy Anchor Link

scripts/lint/seo.mjs holds every route to the system in three modes:

• Static (pnpm lint:seo, in lint:static): every route gets its metadata from seoRoute; a static route's path matches its file; titles and descriptions hold no em dash and descriptions run 50 to 160 characters; the root layout sets no canonical; no file names an alias host; no page writes its own icons or cards.
• Built (after next build in pnpm build): every prerendered page has one title, one description, an absolute canonical on the right host, its card with its size, the robots its policy gives and JSON-LD that parses; the sitemap lists only what the policy lists; indexable titles and descriptions are unique.
• Live (pnpm lint:seo:live against next start or www): every sitemap URL answers 200, every card is the size its head declares, every twin answers Markdown with the right canonical, the agent files answer, and no internal link redirects or breaks.

Adding a routeCopy Anchor Link

1. Call seoRoute with the route's path, title, kind and a description of 50 to 160 characters, and render its jsonLd.
2. Add the route's paths to scripts/build/updated.mjs and run pnpm build:updated, so its lastmod is true.
3. Run pnpm lint:seo, then the build, whose built check reads the new page.