seo-blog

SEO and Blog

Downstream contract: paths like src/ and convex/ refer to the product workspace that adopts Agentic Ship, not this tool repo.

Native Next.js only — @next/mdx, first-party. No CMS, no Contentlayer (unmaintained), no runtime dependency to keep alive.

How this repo publishes (implemented, not planned)

An article is src/app/blog/(articles)/<slug>/page.mdx. The (articles) route group carries the reading layout; /blog is the index. Styling comes from the root mdx-components.tsx, which maps every MDX element to tokens — articles never carry their own classes.

There is no frontmatter. Metadata lives in exactly two places:

1. The page.mdx exports Next's own metadata object — title, description, canonical, OpenGraph. Same API as every other route, checked by TypeScript.
2. src/lib/blog.ts holds the typed ARTICLES index — slug, title, description, publishedAt. The index page and sitemap.ts derive from it; an entry only counts when its page.mdx actually exists.

Publishing = add the folder with page.mdx + add the ARTICLES entry. Both or it is not published.

The slug is frozen once published. Changing it breaks every inbound link; if it truly must change, add a redirect.

Titles under 60 characters with the primary keyword near the front; descriptions 140 to 160 characters, written as the search snippet they are.

Metadata

Use the Metadata API — generateMetadata per route, never hand-written <meta> tags. Every article needs title, description, canonical URL, OpenGraph, and Twitter card. The root layout sets a title template so pages only supply their own title.

Structured data

Emit JSON-LD as a typed object, not a hand-written script string:

• Article on every post — headline, description, datePublished, dateModified, author
• BreadcrumbList on nested routes
• Organization once, in the root layout

Machine surfaces

• src/app/sitemap.ts — generated from the article list, never hand-maintained
• src/app/robots.ts — points at the sitemap and allows AI crawlers by name (GPTBot, ClaudeBot, Claude-User, PerplexityBot, Google-Extended — the file is the authoritative list). Deliberate: being cited by answer engines is distribution. Opting out = editing that one list.
• src/app/llms.txt/route.ts — the AEO counterpart of the sitemap, generated from the SAME typed article index + site.ts, so it cannot go stale separately
• src/app/opengraph-image.tsx — the share card as code (next/og), derived from site.ts; never a stale export
• All of it is asserted in the rendered response by pnpm test:e2e — title, description, OG tags, robots, llms.txt, sitemap, the OG image answering 200. Metadata that exists in code but not in the response is the classic failure.