feat(web): docs SEO + LLM-discoverability — llms.txt, Pagefind search, FAQ JSON-LD (SQLR-36)

[joaoh82]

Implements SQLR-36 — docs SEO + LLM-discoverability for sqlritedb.com.

What changed

Classical docs SEO

• Heading anchors on every section: a hover-visible # link on each /docs <h2> (local H2 helper) and every blog heading (rehype-slug + rehype-autolink-headings). Slugs computed with github-slugger so the ToC and rendered ids always match.
• Blog articles now get an on-page ToC (posts > 600 words) and a tag-ranked Related footer (≥ 3 sibling links with descriptive anchors).
• /docs gets a Related footer (5 links) and a helpful-vote widget.
• Code-fence audit: swept all blog MDX; the one bare fence (an ASCII diagram) now declares ```text.

Search (Pagefind — static, serverless, free)

• postbuild script indexes the prerendered HTML in .next/server/app, scoped via data-pagefind-body (docs + blog only). Custom dark-themed search UI on /docs (docs-search.tsx) using Pagefind's JS API. Index is gitignored (build artifact); next dev degrades to a hint.

LLM surfaces (llmstxt.org)

• /llms.txt — curated index: project tagline + sections of absolute links with one-line summaries (docs, playground, every blog post, GitHub/docs.rs/registries).
• /llms-full.txt — full docs markdown + every blog post concatenated.
• /docs.md — docs page as raw text/markdown for crawlers that prefer markdown.
• All three are force-static (built at build time) via src/lib/llms.ts. Docs markdown source: content/docs/getting-started.md (mirrors docs/page.tsx).
• Typed robots.ts → hand-rolled robots.txt route that references both llms files.

JSON-LD

• No FAQ existed → new landing FAQ section (8 honest Q/A pairs) with FAQPage JSON-LD generated from the same array as the visible <h3>/<p> pairs, so they can't drift.

Analytics (PostHog was already wired)

• Two custom events via a useTrack() hook that no-ops without NEXT_PUBLIC_POSTHOG_KEY: docs-search-query (debounced; query + result count) and docs-helpful-vote (path + boolean). No PII, no cookie banner.

No doc URLs moved (no redirects needed). No CMS. web/README.md updated throughout.

Verification

• npm run typecheck ✅ · npm run lint ✅ (only a pre-existing warning in untouched examples/page.tsx) · npm run build + postbuild ✅ (Pagefind indexed 7 pages).
• New routes return correct status + content-types: /robots.txt, /llms.txt, /llms-full.txt (text/plain), /docs.md (text/markdown), /pagefind/pagefind.js (200).
• JSON-LD validated structurally: SoftwareApplication + FAQPage (8 questions) on /, BlogPosting + BreadcrumbList on posts.
• Browser smoke test (headless, production server): Pagefind module loads and search() returns ranked results with <mark> highlighting; the docs search box (React component) returns 5 results for "transaction" with .html URLs correctly mapped to clean routes; heading-anchor click updates the URL fragment; helpful-vote click → "Thanks!" state; 24 heading anchors + 5 related links present; FAQ renders 8 Q/A pairs. Analytics no-op path confirmed (no PostHog global, no console throw when key absent).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rust-sqlite	Ready	Preview, Comment	Jun 14, 2026 9:50pm