Skip to Content
drksci
System

Discovery

What each page type tells search engines, language models and social platforms, and the one inventory every surface reads.

Discovery is the set of tags, files and images that let something outside the site find a page and describe it: search-engine metadata, structured data, a sitemap and feeds, language-model indexes and Markdown, and social preview images. All of it is built from src/seo, from one list of public pages, so the sitemap, llms.txt, the feeds and the tests cannot disagree about what exists.

Route inventory

routes() in src/seo/inventory.ts lists every public page with its path, title, description, last-modified date, kind, social-image design, breadcrumb trail and whether it may be indexed. Docs and pieces are read from content/, and the résumé from its data. A new page appears in every surface by being in the inventory; no route keeps a list of its own.

Metadata

Each route's generateMetadata calls pageMetadata(path) in src/seo/metadata.ts, and no route writes a tag itself. The builder emits the title, description, canonical URL, authors, keywords, Open Graph, a Twitter summary_large_image card, robots, and the alternate links to the page's Markdown and to both feeds. The root layout sets metadataBase and the title template %s — d/rksci.

Titles are at most 60 characters and descriptions 50 to 160, the limits of the writing guide; bun test fails a page outside them.

Page types

Page typePathOpen Graph typeJSON-LDMarkdownImage design
Landing/websiteWebSite/index.mdlanding
Docs page/docs/<slug>websiteBreadcrumbList/docs/<slug>.mddocs
Piece index/researchwebsiteBreadcrumbList/research.mdindex
Feature piece/<slug>articleScholarlyArticle, BreadcrumbList/<slug>.mdfeature
Write-up piece/<slug>articleArticle, BreadcrumbList/<slug>.mdwriteup
Résumé/blakeprofileProfilePage, BreadcrumbList/blake/cv.mdresume

Every page except the landing page also carries a BreadcrumbList. A piece's Article or ScholarlyArticle has its headline, description, dates, author, image and keywords from its frontmatter; research pieces are ScholarlyArticle and labs pieces are Article. The résumé's Person and ProfilePage are built from the résumé data and add nothing the page does not show. The landing page's WebSite lists a SearchAction that points at the search endpoint, /api/search.

Résumé variants at /blake/<variant> emit the base page's tags with robots noindex. They are left out of the sitemap and llms.txt and keep a Markdown rendition of their own at /blake/<variant>.md.

Indexing policy

Only Vercel production is indexable: VERCEL_ENV=production, or, off Vercel, a production build with SITE_URL set. Every other deployment sends robots noindex, nofollow on each page and serves a robots.txt that disallows everything. sitemap.xml lists every indexable route with its last-modified date.

Feeds

Pieces, newest first, as RSS 2.0 at /feed.xml and JSON Feed 1.1 at /feed.json. Both are linked from the head of every page.

Language models

/llms.txt indexes every page, grouped by section, with a link to its Markdown. /llms-full.txt holds the Markdown of all of them. Any page is at its own path plus .md, and the root is /index.md. For a piece the Markdown keeps the prose, headings, tables and links, and replaces each figure and interactive with its alt text and caption.

Social images

Every page has a 1200 by 630 PNG at /og/<path>/image.png (/og/home/image.png for the landing page), one design per page type, each showing the title, the deck or description, and the kind or section. Colours, type sizes, spacing and font names come from the og-* tokens of the active theme, which SOCIAL_THEME can select by name. The fonts are bundled in src/seo/image/fonts.

Environment

VariableUse
SITE_URLThe site origin. Wins over everything else.
VERCEL_PROJECT_PRODUCTION_URLOrigin in production when SITE_URL is unset.
VERCEL_BRANCH_URL, VERCEL_URLOrigin of a preview deployment.
VERCEL_ENVproduction makes the site indexable.
SOCIAL_THEMEOptional theme name for the social images.

With none of these set, the origin is http://localhost:3000 and the site is not indexable.

Checks

bun test walks the inventory and fails on a missing or over-length title or description, a missing canonical, a missing social image path, a page absent from the sitemap or llms.txt, and a duplicate title. bun scripts/check-site.ts <origin> runs against a started build: every page must answer 200 with one title, one canonical and a social image that answers 200 as image/png.

On this page