---
title: "From Nextra"
description: "Migrate Nextra content, _meta navigation, layouts, and MDX components to Farming Labs Docs"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/nextra"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/nextra.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1500
  task: "Migrate a Nextra documentation site into Farming Labs Docs."
  outcome: "Nextra MDX, routes, navigation order, and supported components run through the Farming Labs Next.js adapter or another selected target runtime."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Identify whether Nextra content uses content, pages, app page.mdx files, or a mixed layout."
    - "Preserve _meta files, next.config, theme config, mdx-components, public assets, and custom components."
    - "Initialize the target runtime in a migration branch."
  files:
    - "next.config.js"
    - "next.config.mjs"
    - "theme.config.tsx"
    - "mdx-components.tsx"
    - "docs.config.ts"
    - "docs.config.tsx"
  commands:
    - run: "npx @farming-labs/docs init"
      description: "Configure Farming Labs Docs in the target application."
  sideEffects:
    - "Nextra routing and layout wiring are replaced by the Farming Labs adapter and docs configuration."
  verification:
    - description: "Build the target and compare Nextra routes, sidebar order, imported components, assets, and metadata."
      expect: "The production build passes and required routes resolve as HTML and Markdown."
  rollback:
    - "Restore the previous Next.js configuration and Nextra route files from the migration branch."
  failureModes:
    - symptom: "The same content is discovered twice."
      resolution: "Choose one Nextra source layout, move it once, and remove duplicate catch-all routes only after the target works."
    - symptom: "Nextra theme components fail to resolve."
      resolution: "Replace them with Farming Labs MDX components or register a local equivalent."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Migrate a Nextra documentation site into Farming Labs Docs.
Outcome: Nextra MDX, routes, navigation order, and supported components run through the Farming Labs Next.js adapter or another selected target runtime.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- Identify whether Nextra content uses content, pages, app page.mdx files, or a mixed layout.
- Preserve _meta files, next.config, theme config, mdx-components, public assets, and custom components.
- Initialize the target runtime in a migration branch.

### Files

- `next.config.js`
- `next.config.mjs`
- `theme.config.tsx`
- `mdx-components.tsx`
- `docs.config.ts`
- `docs.config.tsx`

### Commands

- `npx @farming-labs/docs init` — Configure Farming Labs Docs in the target application.

### Side Effects

- Nextra routing and layout wiring are replaced by the Farming Labs adapter and docs configuration.

### Verification

- Build the target and compare Nextra routes, sidebar order, imported components, assets, and metadata.
  - Expected: The production build passes and required routes resolve as HTML and Markdown.

### Rollback

- Restore the previous Next.js configuration and Nextra route files from the migration branch.

### Failure Modes

- The same content is discovered twice. — Recovery: Choose one Nextra source layout, move it once, and remove duplicate catch-all routes only after the target works.
- Nextra theme components fail to resolve. — Recovery: Replace them with Farming Labs MDX components or register a local equivalent.
<!-- farming-labs:agent-contract:end -->

# From Nextra

## From Nextra task

Task: Migrate a Nextra documentation site into Farming Labs Docs.

Expected result: Nextra MDX, routes, navigation order, and supported components run through the Farming Labs Next.js adapter or another selected target runtime.

## From Nextra prerequisites

- Identify whether Nextra content uses content, pages, app page.mdx files, or a mixed layout.
- Preserve _meta files, next.config, theme config, mdx-components, public assets, and custom components.
- Initialize the target runtime in a migration branch.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Nextra verification

- Build the target and compare Nextra routes, sidebar order, imported components, assets, and metadata. Expected: The production build passes and required routes resolve as HTML and Markdown.
- Failure: The same content is discovered twice.
- Recovery: Choose one Nextra source layout, move it once, and remove duplicate catch-all routes only after the target works.
- Rollback: Restore the previous Next.js configuration and Nextra route files from the migration branch.

## From Nextra agent guidance

Detect the Nextra content convention before changing routes: root or src content directory, Pages
Router files, App Router page.mdx files, or a mixed setup. Snapshot the page map and published
routes. Never keep both the old Nextra catch-all and the new Farming Labs route active at the same
URL.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).