Docs redesign

Summarized approach

• Content: content/docs/<section>/*.mdx + content/blog/*.mdx with frontmatter, mirroring your route tree.
• Loader: lib/content.ts — fs + gray-matter, builds the nav tree, slug index, and TOC. Wrapped in React cache.
• Route: app/docs/[[...slug]]/page.tsx with generateStaticParams + dynamicParams = false → every page prerendered, unknown slugs 404 at build.
• MDX render: next-mdx-remote/rsc (or Velite) with rehype-pretty-code (Shiki, build-time), rehype-slug, autolink headings, remark-gfm. Interactive bits (<ComponentPreview>, copy button, theme toggle, search, mobile nav) are small "use client" islands.
• Search: Pagefind indexes built HTML in a post-build step; search UI is a lazy island.
• SEO: per-page generateMetadata, sitemap.ts, robots.ts, JSON-LD, static OG images.

Project Structure

app/*                  → route and render management (routing files only)
content/*              → all markdown content
components/*           → any shared components used to render templated routes
lib/*                  → utilities for 3rd party libs
lib/site-config.ts     → SEO Metadata config

App Structure

app/
  (marketing)/page.tsx            → landing
  docs/[[...slug]]/page.tsx       → all six sections, driven by content dir
  blog/page.tsx                   → blog landing
  blog/[slug]/page.tsx            → blog

Content

Content is any markdown page that is expected to be rendered by a route path. Directory structure matches the route path.

content/
  docs/get-started/*.mdx
  docs/components/*.mdx
  docs/signals/*.mdx
  docs/data-grid/*.mdx
  docs/styling/*.mdx
  docs/theming/*.mdx
  blog/*.mdx

Search: Pagefind as a post-build step

Pagefind indexes the built HTML, so it runs after next build:

• Build command becomes roughly next build && pagefind --site <build-output> --output-path public/pagefind.
• The index (static .pf files) is served as a static asset; the search UI is a lazy-loaded client island that only fetches the index when the user opens search.
• Zero backend, zero API keys, scales to thousands of pages, and stays consistent with the fully-static model. (I'll confirm the exact --site source dir against your final output during build — that's the one fiddly bit on Vercel.)

SEO layer (built in from the start)

• generateMetadata per page from frontmatter (title, description, canonical, OG).
• app/sitemap.ts + app/robots.ts generated from the content tree.
• JSON-LD structured data: TechArticle for docs, BlogPosting for blog.
• Build-time OG images via opengraph-image.tsx (satori) per page.
• Semantic HTML, one <h1>, heading anchors, and the security response headers in next.config.