chore: migrate to fumadocs and nextjs app router

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "dev",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["dev", "--port", "3333", "--hostname", "0.0.0.0"],
+      "port": 3333
+    }
+  ]
+}

.gitignore

@@ -123,4 +123,7 @@ fabric.properties
 !.idea/codeStyles
 !.idea/runConfigurations
 
-# End of https://www.toptal.com/developers/gitignore/api/intellij+all
+# End of https://www.toptal.com/developers/gitignore/api/intellij+all
+
+# fumadocs-mdx generated
+.source/

.source/source.config.mjs

@@ -0,0 +1,124 @@
+// source.config.ts
+import { defineDocs, defineConfig, frontmatterSchema } from "fumadocs-mdx/config";
+import remarkGfm from "remark-gfm";
+import { mdxJsxToMarkdown } from "mdast-util-mdx-jsx";
+import { z } from "zod";
+var yamlDateField = z.union([
+  z.string(),
+  z.date().transform((d) => d.toISOString().split("T")[0])
+]).nullish();
+var blogFrontmatterSchema = frontmatterSchema.extend({
+  date: yamlDateField,
+  tag: z.string().nullish(),
+  author: z.string().nullish(),
+  ogImage: z.string().nullish(),
+  showInBlogIndex: z.boolean().nullish()
+});
+var changelogFrontmatterSchema = frontmatterSchema.extend({
+  date: yamlDateField,
+  author: z.string().nullish(),
+  ogImage: z.string().nullish()
+});
+var customerFrontmatterSchema = frontmatterSchema.extend({
+  // Use .nullish() so empty YAML values (parsed as null) are accepted too
+  date: yamlDateField,
+  ogImage: z.string().nullish(),
+  tag: z.string().nullish(),
+  author: z.string().nullish(),
+  customerLogo: z.string().nullish(),
+  customerLogoDark: z.string().nullish(),
+  customerQuote: z.string().nullish(),
+  quoteAuthor: z.string().nullish(),
+  quoteRole: z.string().nullish(),
+  quoteCompany: z.string().nullish(),
+  quoteAuthorImage: z.string().nullish(),
+  showInCustomerIndex: z.boolean().nullish()
+});
+var docs = defineDocs({
+  dir: "content/docs"
+});
+var selfHosting = defineDocs({
+  dir: "content/self-hosting"
+});
+var blog = defineDocs({
+  dir: "content/blog",
+  docs: {
+    schema: blogFrontmatterSchema
+  }
+});
+var changelog = defineDocs({
+  dir: "content/changelog",
+  docs: {
+    schema: changelogFrontmatterSchema
+  }
+});
+var guidesFrontmatterSchema = frontmatterSchema.extend({
+  ogImage: z.string().nullish(),
+  category: z.string().nullish()
+});
+var guides = defineDocs({
+  dir: "content/guides",
+  docs: {
+    schema: guidesFrontmatterSchema
+  }
+});
+var faq = defineDocs({
+  dir: "content/faq"
+});
+var integrations = defineDocs({
+  dir: "content/integrations"
+});
+var security = defineDocs({
+  dir: "content/security"
+});
+var library = defineDocs({
+  dir: "content/library"
+});
+var customers = defineDocs({
+  dir: "content/customers",
+  docs: {
+    schema: customerFrontmatterSchema
+  }
+});
+var handbook = defineDocs({
+  dir: "content/handbook"
+});
+var marketing = defineDocs({
+  dir: "content/marketing"
+});
+var source_config_default = defineConfig({
+  mdxOptions: {
+    remarkPlugins: [remarkGfm],
+    providerImportSource: "@/mdx-components",
+    // Disable remark-image: many content files reference remote images via https://
+    // and the plugin tries to fetch dimensions at compile time, causing build failures
+    remarkImageOptions: false,
+    // Teach remark-structure's mdast-util-to-markdown serializer how to handle
+    // MDX JSX nodes (mdxJsxFlowElement / mdxJsxTextElement). Without this, it
+    // throws "Cannot handle unknown node `mdxJsxFlowElement`" when pages contain
+    // JSX components like <Callout>, <Tabs>, etc.
+    remarkStructureOptions: {
+      // @ts-ignore — extensions is valid in mdast-util-to-markdown but the
+      // StructureOptions type doesn't expose it directly
+      stringify: { extensions: [mdxJsxToMarkdown()] }
+    },
+    // @ts-ignore — { lazy: false } is valid at runtime; RehypeCodeOptions
+    // requires themes in its full type but fumadocs applies safe defaults
+    rehypeCodeOptions: { lazy: false }
+  }
+});
+export {
+  blog,
+  changelog,
+  customers,
+  source_config_default as default,
+  docs,
+  faq,
+  guides,
+  handbook,
+  integrations,
+  library,
+  marketing,
+  security,
+  selfHosting
+};

MIGRATION.md

@@ -0,0 +1,98 @@
+# Nextra → Fumadocs + App Router Migration
+
+This document describes the migration from Nextra (Pages Router) to Fumadocs (App Router) and the remaining steps to complete it.
+
+## What’s done
+
+1. **Dependencies**
+   - Replaced `nextra` and `nextra-theme-docs` with `fumadocs-core`, `fumadocs-mdx`, and `fumadocs-ui`.
+   - Added `@types/mdx` in devDependencies.
+
+2. **Config**
+   - **`source.config.ts`** – Fumadocs MDX config: `defineDocs({ dir: 'content/docs' })`, `remarkGfm`, `providerImportSource: '@/mdx-components'`.
+   - **`lib/source.ts`** – Fumadocs source: `loader()` with `docs.toFumadocsSource()`, `baseUrl: '/docs'`.
+   - **`next.config.mjs`** – Removed Nextra; wrapped config with `createMDX()` from `fumadocs-mdx/next`. All existing options (headers, redirects, rewrites, images, etc.) are unchanged.
+   - **`tsconfig.json`** – Added path `"fumadocs-mdx:collections/*": [".source/*"]`.
+
+3. **App Router**
+   - **`app/layout.tsx`** – Root layout: `RootProvider` (from `fumadocs-ui/provider/next`), Geist fonts, global CSS (`style.css`, overrides, Vidstack).
+   - **`app/page.tsx`** – Temporary home: title + link to `/docs`. Replace with the real landing (e.g. current `<Home />`) when ready.
+   - **`app/docs/layout.tsx`** – `DocsLayout` with `source.getPageTree()`, nav title “Langfuse”, GitHub link.
+   - **`app/docs/[[...slug]]/page.tsx`** – Doc page: `source.getPage(slug)`, `page.data.load()`, `DocsPage` + `DocsBody` with MDX and `getMDXComponents()`; `generateMetadata` and `generateStaticParams`.
+
+4. **MDX**
+   - **`mdx-components.tsx`** – `getMDXComponents` / `useMDXComponents` using `fumadocs-ui/mdx`.
+
+5. **Content**
+   - **`content/docs/`** – New Fumadocs content root:
+     - `meta.json` – root meta with `pages: ["index", "observability"]`.
+     - `index.mdx` – overview doc.
+     - `observability/meta.json` and `observability/overview.mdx` – sample observability doc.
+
+## Install and peer deps
+
+- Fumadocs MDX 13 expects **Next 15.3+** and **fumadocs-core 15+**. If you stay on Next 15.2.x, use:
+  - `pnpm install --legacy-peer-deps` (or `npm install --legacy-peer-deps`).
+- Optional: upgrade to Next `^15.3.0` to satisfy peer deps without `--legacy-peer-deps`.
+
+## Remaining steps
+
+### 1. Content migration (docs)
+
+- **Done.** Docs live in `content/docs/` with Fumadocs `meta.json`. The former `pages/docs/` content was migrated; `docs-nextra-backup` was removed after verification.
+
+### 2. Other sections (blog, changelog, guides, etc.) — done
+
+- **Done.** All main sections are on App Router:
+  - **Fumadocs collections** in `source.config.ts`: `selfHosting`, `blog`, `changelog`, `guides`, `faq`, `integrations`, `security`, `library`, `customers`, `handbook`.
+  - **Content** in `content/<section>/`.
+  - **App routes**: `app/docs/` (docs), `app/blog/`, `app/changelog/` (index + layout), and `app/[section]/[[...slug]]` for self-hosting, guides, faq, integrations, security, library, customers, handbook.
+  - **Client loaders** for section MDX: `lib/section-loaders.generated.ts` (generated in prebuild via `scripts/generate-section-loaders.js`).
+  - **Index components** (`BlogIndex`, `ChangelogIndex`) use `getPagesUnderRoute` from nextra-shim, which now reads from Fumadocs sources via `getPagesForRoute` in `lib/source.ts`.
+- **Static marketing pages** are in `content/marketing/` and served via `app/[section]` (section = about, careers, pricing, etc.).
+
+### 3. Replace Nextra usage in components
+
+These (and any others that import from Nextra) need to be updated or replaced:
+
+| File | Nextra usage | Fumadocs / replacement |
+|------|--------------|-------------------------|
+| `theme.config.tsx` | Entire file | No longer used. Nav/sidebar/footer are in `app/docs/layout.tsx` and Fumadocs layout props. Replicate any custom nav/links in `DocsLayout` (e.g. `nav`, `sidebar`, `links`). |
+| `components/*` using `getPagesUnderRoute`, `Page`, `useConfig`, `useTheme` | `nextra/context`, `nextra-theme-docs` | Use `source` from `@/lib/source`: e.g. `source.getPages()`, filter by path; or build custom indexes from `source.getPageTree()`. For theme, use `next-themes` or Fumadocs theme. |
+| `nextra/components`: `Cards`, `Tabs`, `Callout` | Nextra components | Use Fumadocs UI: `fumadocs-ui/components/card`, `fumadocs-ui/components/tabs`, `fumadocs-ui/components/callout`, or keep local wrappers that match Fumadocs props. |
+
+Notable components to refactor:
+
+- `components/home/*` (Changelog, etc.) – replace `getPagesUnderRoute` with `source` + path filter.
+- `components/blog/BlogIndex.tsx`, `components/changelog/ChangelogIndex.tsx` – same.
+- `components/faq/FaqIndex.tsx`, `components/customers/CustomerIndex.tsx`, `components/CookbookIndex.tsx`, `components/VideoIndex.tsx`, `components/integrations/IntegrationIndex.tsx` – same.
+- `components/MainContentWrapper.tsx`, `components/LangTabs.tsx`, etc. – remove `useConfig` / Nextra theme; use Fumadocs layout or local state.
+- `components/not-found-animation.tsx`, `components/MetabaseDashboard.tsx`, `components/inkeep/useInkeepSettings.ts` – replace `useTheme` with `next-themes` or Fumadocs theme.
+
+### 4. Home and global providers — done
+
+- **`app/page.tsx`** – Uses real `<Home />` from `@/components/home`.
+- **Analytics and scripts** – In `app/layout.tsx`: PostHog (via `@/components/analytics/PostHogProvider`), Hubspot, and Cookieyes scripts (production only).
+
+### 5. Remove Pages Router — done
+
+- **Done.** The `pages/` directory has been removed. The site uses **App Router only**.
+- All routes are under `app/`; content lives under `content/`. API routes are under `app/api/`.
+
+### 6. Optional: Fumadocs search
+
+- Configure search (e.g. Fumadocs search or Inkeep) in the root layout or docs layout (e.g. `RootProvider` or `DocsLayout` search options), and remove any Nextra search wiring.
+
+## Running the project
+
+- Generate Fumadocs source (usually automatic with Next):
+  - `npx fumadocs-mdx` (or add to `postinstall` if you want types on install).
+- Dev: `pnpm dev` (or `npm run dev`).
+- Build: `pnpm build` (or `npm run build`). If you hit peer dependency errors, use `pnpm install --legacy-peer-deps` or upgrade Next as above.
+
+## Reference
+
+- [Fumadocs – Get started](https://fumadocs.dev/docs)
+- [Fumadocs MDX – Next.js](https://fumadocs.dev/docs/mdx/next)
+- [Fumadocs UI – Docs layout](https://fumadocs.dev/docs/ui/layouts/docs)
+- [Fumadocs navigation / meta](https://fumadocs.dev/docs/navigation)

README.md

@@ -12,6 +12,8 @@ You can easily contribute to the docs using GitHub Codespaces. Just click on the
 
 Pre-requisites: Node.js 22, pnpm v9.5.0
 
+To use Node 22 (e.g. with [nvm](https://github.com/nvm-sh/nvm)): `nvm install 22` then `nvm use` (or `nvm use 22`). The repo includes an `.nvmrc` so `nvm use` picks 22 automatically.
+
 1. Optional: Create env based on [.env.template](./.env.template)
 2. Run `pnpm i` to install the dependencies.
 3. Run `pnpm dev` to start the development server on localhost:3333
@@ -57,7 +59,7 @@ Interested in stack of Q&A docs chatbot? Checkout the [blog post](https://langfu
 
 The docs site includes four interconnected features designed to make documentation accessible to LLMs and AI tools:
 
-1. **Markdown URL endpoints** (`.md` suffix): Append `.md` to any URL (e.g., `/docs.md`) to get raw markdown. Built at compile time via `scripts/copy_md_sources.js` which copies all `.mdx` files from `/pages` to `/public/md-src/` as static `.md` files with inlined MDX components.
+1. **Markdown URL endpoints** (`.md` suffix): Append `.md` to any URL (e.g., `/docs.md`) to get raw markdown. Built at compile time via `scripts/copy_md_sources.js` which copies all `.mdx`/`.md` files from `content/` to `public/md-src/` as static `.md` files with inlined MDX components.
 
 2. **Copy as Markdown button**: UI button on docs pages that fetches the `.md` endpoint and copies to clipboard for pasting into ChatGPT/Claude/Cursor.
 

app/(home)/layout.tsx

@@ -0,0 +1,9 @@
+import { Layout } from "@/components/layout";
+
+export default function HomeLayoutRoute({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <Layout>{children}</Layout>;
+}

app/(home)/page.tsx

@@ -0,0 +1,5 @@
+import { Home } from "@/components/home";
+
+export default function HomePage() {
+  return <Home />;
+}

app/(wide)/WideSectionPage.tsx

@@ -0,0 +1,31 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { SECTION_CONFIG, WIDE_SECTIONS } from "@/lib/sections";
+import type { WideSectionSlug } from "@/lib/sections";
+import { SectionDocBodyClient } from "@/app/[section]/SectionDocBodyClient";
+
+export async function generateWideSectionMetadata(section: WideSectionSlug): Promise<Metadata> {
+  const config = SECTION_CONFIG[section as keyof typeof SECTION_CONFIG];
+  const page = config.source.getPage([section]);
+  if (!page) return { title: "Not Found" };
+  return {
+    title: page.data.title,
+    description: page.data.description ?? undefined,
+  };
+}
+
+type Props = { section: WideSectionSlug };
+
+export default async function WideSectionPage({ section }: Props) {
+  if (!WIDE_SECTIONS.has(section)) notFound();
+  const config = SECTION_CONFIG[section as keyof typeof SECTION_CONFIG];
+  const page = config.source.getPage([section]);
+  if (!page) notFound();
+
+  return (
+    <SectionDocBodyClient
+      collection={config.collection}
+      slugPromise={Promise.resolve({ slug: [section] })}
+    />
+  );
+}

app/(wide)/layout.tsx

@@ -0,0 +1,20 @@
+import { Layout } from "@/components/layout";
+import { MainContentWrapper } from "@/components/MainContentWrapper";
+
+/**
+ * Layout for wide marketing sections (pricing, enterprise, etc.) that have
+ * their own route folders. No sidebar, no prose, max-w-7xl content.
+ */
+export default function WideSectionLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <Layout>
+      <div className="mx-auto w-full max-w-7xl px-4 py-6 sm:px-6 lg:px-8">
+        <MainContentWrapper>{children}</MainContentWrapper>
+      </div>
+    </Layout>
+  );
+}

app/(wide)/pricing-self-host/page.tsx

@@ -0,0 +1,10 @@
+import type { Metadata } from "next";
+import WideSectionPage, { generateWideSectionMetadata } from "../WideSectionPage";
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateWideSectionMetadata("pricing-self-host");
+}
+
+export default function Page() {
+  return <WideSectionPage section="pricing-self-host" />;
+}

app/(wide)/pricing/page.tsx

@@ -0,0 +1,10 @@
+import type { Metadata } from "next";
+import WideSectionPage, { generateWideSectionMetadata } from "../WideSectionPage";
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateWideSectionMetadata("pricing");
+}
+
+export default function Page() {
+  return <WideSectionPage section="pricing" />;
+}

app/(wide)/startups/page.tsx

@@ -0,0 +1,10 @@
+import type { Metadata } from "next";
+import WideSectionPage, { generateWideSectionMetadata } from "../WideSectionPage";
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateWideSectionMetadata("startups");
+}
+
+export default function Page() {
+  return <WideSectionPage section="startups" />;
+}

app/(wide)/talk-to-us/page.tsx

@@ -0,0 +1,10 @@
+import type { Metadata } from "next";
+import WideSectionPage, { generateWideSectionMetadata } from "../WideSectionPage";
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateWideSectionMetadata("talk-to-us");
+}
+
+export default function Page() {
+  return <WideSectionPage section="talk-to-us" />;
+}

app/(wide)/watch-demo/page.tsx

@@ -0,0 +1,10 @@
+import type { Metadata } from "next";
+import WideSectionPage, { generateWideSectionMetadata } from "../WideSectionPage";
+
+export async function generateMetadata(): Promise<Metadata> {
+  return generateWideSectionMetadata("watch-demo");
+}
+
+export default function Page() {
+  return <WideSectionPage section="watch-demo" />;
+}