Hive Docs Migration PRD

[hasparus]

Hive Docs Migration PRD

Overview

Migrate GraphQL Hive documentation from Nextra/Next.js to Fumadocs/TanStack Start.

Why

Too many abstraction layers. Next.js → Nextra → nextra-theme-docs → @theguild/components → our docs. We locked Nextra version earlier to avoid upgrade pain and we use patch-package liberally. Details
DX pains. Transient errors requiring rm -rf node_modules, build time.
LLMs waste tokens on HTML. No /llms.txt, no structured markdown export. AI assistants parsing our HTML erode their context window and get confused by navigation, footers, and scripts.

Goals

1. Drop Nextra
2. LLM-ready docs - /llms.txt endpoints already implemented
3. Visual parity - Match existing design via new design-system package
4. Preserve URLs - No redirects, no SEO churn

Who Uses These Docs

Engineers using Hive, SREs self-hosting it, evaluators comparing solutions, LLMs.

Scope

Content to Migrate

Type	Count	Source Path
Documentation	158	content/
Blog posts	129	app/blog/(posts)/
Product updates	59	app/product-updates/(posts)/
Case studies	3	app/case-studies/(posts)/
Landing pages	~10	app/*.tsx (home, pricing, partners, etc.)
Total	~359

Components to Port

• Layout: HiveLayout, HiveNavigation, HiveFooter, NarrowPages
• Content: Callout, FeatureTabs, CodeSandbox, StackBlitz, VideoEmbed, Comparison
• Blog: BlogCard, BlogPostLayout, Newsletter, Author cards
• Landing: HeroSection, CommunitySection, PricingSlider, PlansTable, FAQ

Not Doing

• i18n - English only. No translation infrastructure.
• Versioned docs - Single version. Old versions via git history.
• Interactive playground - Keep linking to external tools (StackBlitz, CodeSandbox)
• Comments on docs pages - Blog has Giscus, docs don't need it.
• PDF export - Not a use case we've heard.

Technical Architecture

Stack Comparison

Aspect	Old (Nextra)	New (Fumadocs)
Framework	Next.js	TanStack Start
Bundler	Turbopack	Vite
MDX	@theguild/components (wraps Nextra)	fumadocs-mdx
Search	Pagefind	Orama
Diagrams	Mermaid.js	rehype-mermaid

Both use Shiki for syntax highlighting.

URL Structure

/docs/                          # Documentation root
/docs/schema-registry/...       # Console features
/docs/gateway/...               # Hive Gateway
/docs/router/...                # Hive Router
/docs/api-reference/...         # CLI, GraphQL API, clients
/blog/                          # Blog index
/blog/[slug]                    # Blog posts
/product-updates/               # Product updates timeline
/case-studies/                  # Case studies
/pricing                        # Pricing page
/partners                       # Partners page
/                               # Home landing page

Navigation Migration

Current: 28 _meta.ts files defining hierarchical navigation
Target: Convert _meta.ts → Fumadocs meta.json

Features

Already Implemented in Target

• Fumadocs + TanStack Start scaffold
• Mermaid diagram support
• Twoslash TypeScript code blocks
• Orama search endpoint
• LLM endpoints (/llms.txt, /llms-full.txt, /llms.mdx/docs/$)
• Content negotiation (Accept: text/markdown)
• Design-system package structure
• Vite + Turbo build pipeline

To Implement

• MDX content migration (~359 files)
• Navigation hierarchy (_meta.ts → meta.json)
• Port components
• Blog (tags, feed, similar posts)
• Product updates timeline
• Case studies
• Landing pages
• RSS feed generation
• Sitemap generation
• OpenGraph images
• Contact form modal to use instead of Giscus

Migration Strategy

Phase 0: Staging Deploy ✓ (exists on ci branch)

Current state:

• Vercel deployment (temporary, to personal account)
• nitro({ preset: "vercel" }) in vite.config.ts
• Prerender disabled - TanStack Start has path bug with Vercel preset
• PR previews working
• Lint + typecheck workflows active

CI workflows on origin/ci:

• .github/workflows/website.yml - deploys to Vercel
• .github/workflows/pr.yml - lint, typecheck, preview on PRs
• .github/workflows/main.yml - same + prod deploy on main

Known issues:

• Prerender needs TanStack Start fix / workaround / further investigation

Phase 1: Landing Pages

• / (home)
• /pricing
• /federation
• /gateway
• /ecosystem
• /partners
• /oss-friends
• /case-studies

Phase 2: Component Library

Port components as pages require them.

• Set up Storybook or consider alternatives.

Phase 3: Content

1. Define meta.json structure matching existing hierarchy
2. Set up content collections for each type (docs, blog, product-updates, case-studies)
3. Migrate MDX content:
   • Preserve git history (use git mv or subtree merge)
   • Transform frontmatter if needed
   • Update component imports

Phase 4: Blog & Feeds

1. Implement blog collection with tags
2. Add RSS feed route
3. Newsletter signup forms

Phase 5: Polish & Deploy

1. Sitemap generation
2. OpenGraph image generation
3. Lighthouse CI setup - run on every PR, establish baseline from current site
4. Final URL verification (crawl all paths, assert 200s)
5. Fix prerender or accept SSR-only and add cache headers
6. Production DNS cutover

Assumptions

• Visual parity is "good enough", not pixel-perfect
• Content structure doesn't need major information architecture changes

What Could Go Wrong

• Visual drift. Snapshot current site with playwright + odiff.

• Search quality unknown. Pagefind → Orama is a different engine.

  • It generally feels better from my perspective, but we can try to compare quantatively.

• Missed pages. We'll compare the sitemaps to double check.

• 404 links. We already have an MDX link checker CI workflow. It should be updated to run on Node 24, but it should work with Fumadocs.

Success Metrics

1. URLs: 100% of existing URLs return 200 (todo: write automated check, compare generated sitemaps)
2. LLM endpoints: /llms.txt, /llms-full.txt serve all content
3. Lighthouse CI: Run on every PR, track regressions (not blocking)
4. Visual parity: Snapshot comparison for review, not gating. We can do some improvements or accept some Fuma defaults during migration.

Open

• Analytics provider: Plausible? Fathom? Google Analytics?