Migrate documentation from GitBook to Nextra

[seanspeaks]

Summary

Migrate the Frigg Framework documentation from GitBook to a self-hosted Nextra (Next.js) documentation site. This will provide better control over the documentation experience, enable analytics integration, and support an MCP server for AI-assisted documentation queries.

Background & Rationale

Why migrate away from GitBook?

1. Limited customization - GitBook's theme and layout options are constrained
2. No analytics control - Cannot integrate PostHog or other preferred analytics platforms
3. MCP server support - Need to build an MCP server that indexes documentation for AI queries; self-hosted solution provides full control over content structure
4. OpenAPI integration - Want to use Scalar for interactive API documentation with v1/v2 version selector

Why Nextra?

• Simple & Responsive - Gets out of the way, focuses on content
• Markdown-based - Easy migration from GitBook's markdown files
• Next.js foundation - Full React ecosystem, SSG/ISR support, excellent performance
• Built-in features - Search, dark mode, syntax highlighting, MDX support
• Active community - Well-maintained, Vercel-backed
• Theme flexibility - Docs theme perfect for technical documentation

Proposed Architecture

docs-site/
├── pages/
│   ├── _app.tsx              # PostHog, theme providers
│   ├── _meta.json            # Navigation structure
│   ├── index.mdx             # Welcome page
│   ├── getting-started/
│   │   ├── _meta.json
│   │   ├── quick-start.mdx
│   │   └── configuration.mdx
│   ├── tutorials/
│   │   ├── _meta.json
│   │   └── ...
│   ├── guides/
│   ├── reference/
│   │   ├── _meta.json
│   │   ├── core-concepts.mdx
│   │   ├── architecture.mdx
│   │   └── api-reference.mdx   # Links to Scalar
│   ├── api-modules/
│   │   ├── _meta.json
│   │   ├── overview.mdx
│   │   ├── building-your-own.mdx
│   │   └── [module]/           # Dynamic routes for each module
│   ├── api/
│   │   └── index.tsx           # Scalar API reference page
│   ├── contributing/
│   └── support/
├── components/
│   ├── ScalarApiReference.tsx  # Scalar embed component
│   └── PostHogProvider.tsx     # Analytics wrapper
├── public/
│   └── images/                 # Static assets
├── styles/
│   └── globals.css             # Custom styles
├── scripts/
│   └── build-mcp-index.js      # Generate MCP-compatible index
├── next.config.js
├── theme.config.tsx            # Nextra theme configuration
├── package.json
└── tsconfig.json

Key Features

1. Scalar API Reference Integration

Embed Scalar with v1/v2 version selector using the dynamic OpenAPI specs already implemented:

// pages/api/index.tsx
import { ScalarApiReference } from '@scalar/nextjs-api-reference'

export default function ApiDocs() {
  return (
    <ScalarApiReference
      sources={[
        { title: 'API v2 (Current)', slug: 'v2', url: '/api/openapi-v2.json' },
        { title: 'API v1 (Legacy)', slug: 'v1', url: '/api/openapi-v1.json' }
      ]}
    />
  )
}

2. PostHog Analytics

Track documentation usage, popular pages, search terms, and user journeys:

// components/PostHogProvider.tsx
import posthog from 'posthog-js'
import { PostHogProvider } from 'posthog-js/react'

// Initialize in _app.tsx
posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY, {
  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
  capture_pageview: true
})

3. MCP Server for Documentation

Create a simple MCP server that indexes documentation content:

// mcp-server/index.js
const { Server } = require('@modelcontextprotocol/sdk/server');

// Index all MDX files for semantic search
// Expose tools: search_docs, get_page, list_sections

4. Navigation Structure (from existing SUMMARY.md)

{
  "index": "Welcome",
  "getting-started": "Getting Started",
  "tutorials": "Tutorials",
  "guides": "How-To Guides",
  "reference": "Reference",
  "api-modules": "API Modules",
  "api": "API Reference",
  "contributing": "Contributing",
  "support": "Support"
}

Migration Plan

Phase 1: Setup & Infrastructure

1. Create docs-site/ directory in frigg repo
2. Initialize Next.js with Nextra docs theme
3. Configure theme, navigation, and basic styling
4. Set up PostHog analytics
5. Create Scalar API reference page

Phase 2: Content Migration

1. Convert SUMMARY.md structure to Nextra _meta.json files
2. Migrate core pages (Welcome, Getting Started, Quick Start)
3. Migrate Reference section (Core Concepts, Architecture, Data Model)
4. Migrate API Modules documentation
5. Migrate Tutorials and Guides

Phase 3: MCP Server

1. Create markdown indexing script
2. Build MCP server with search_docs, get_page, list_sections tools
3. Test with Claude Code
4. Document MCP server usage

Phase 4: Deployment & Cutover

1. Deploy to Vercel (or similar)
2. Configure docs.friggframework.org DNS
3. Redirect old GitBook URLs
4. Remove GitBook configuration

Acceptance Criteria

Must Have

• Nextra docs site builds and runs locally
• All existing documentation content is migrated
• Scalar API reference with v1/v2 version selector works
• PostHog analytics tracks page views
• Navigation matches existing structure
• Dark mode support
• Mobile responsive design
• Search functionality works

Should Have

• MCP server indexes all documentation
• MCP server provides search_docs tool
• Custom 404 page
• SEO meta tags on all pages
• Sitemap generation
• Old GitBook URL redirects

Nice to Have

• API module documentation auto-generated from package metadata
• Version selector for framework versions
• Edit on GitHub links
• Community feedback/rating system

Technical Decisions

Dependencies

• next ^14.x
• nextra ^2.x
• nextra-theme-docs ^2.x
• @scalar/nextjs-api-reference ^1.x
• posthog-js ^1.x
• @modelcontextprotocol/sdk (for MCP server)

Hosting

• Recommended: Vercel (native Next.js support, excellent DX)
• Alternative: Self-hosted via Docker, Netlify, Cloudflare Pages

Content Format

• MDX for all pages (enables React components in markdown)
• YAML frontmatter for page metadata
• Callouts using Nextra's built-in components

References

• Nextra Documentation
• Scalar Next.js Integration
• PostHog Next.js Integration
• MCP SDK Documentation
• Current GitBook docs: docs.friggframework.org
• OpenAPI specs: packages/core/openapi/openapi-v1.yaml, openapi-v2.yaml