---
title: "From Docusaurus"
description: "Migrate Docusaurus docs, sidebars, versions, components, and assets to Farming Labs Docs"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/docusaurus"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/docusaurus.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1700
  task: "Migrate a Docusaurus documentation site into a supported Farming Labs Docs runtime."
  outcome: "Docusaurus pages, sidebar order, assets, and supported MDX patterns render in a buildable Farming Labs Docs project."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Preserve docusaurus.config, sidebars, docs, static, versions.json, versioned_docs, and versioned_sidebars."
    - "Decide which Docusaurus docs versions and locales must remain public."
    - "Initialize the target runtime in a branch or separate directory."
  files:
    - "docusaurus.config.js"
    - "docusaurus.config.ts"
    - "sidebars.js"
    - "sidebars.ts"
    - "docs.config.ts"
    - "docs.config.tsx"
  commands:
    - run: "npx @farming-labs/docs init"
      description: "Scaffold the target docs runtime before copying Docusaurus content."
  sideEffects:
    - "Docusaurus navigation metadata and MDX components are rewritten for the target runtime."
  verification:
    - description: "Build the target and compare every published Docusaurus route, sidebar group, version, and asset."
      expect: "Required routes resolve, the production build passes, and unsupported components are explicitly tracked."
  rollback:
    - "Keep the original Docusaurus deployment and restore the migration branch if route or version checks fail."
  failureModes:
    - symptom: "MDX compilation fails on a Docusaurus import or JSX component."
      resolution: "Replace the import with a Farming Labs component or preserve the component as a registered custom MDX component."
    - symptom: "A versioned URL no longer resolves."
      resolution: "Copy that version into an explicit target path or add a redirect before cutover."
---

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

Task: Migrate a Docusaurus documentation site into a supported Farming Labs Docs runtime.
Outcome: Docusaurus pages, sidebar order, assets, and supported MDX patterns render in a buildable Farming Labs Docs project.

### Applies To

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

### Prerequisites

- Preserve docusaurus.config, sidebars, docs, static, versions.json, versioned_docs, and versioned_sidebars.
- Decide which Docusaurus docs versions and locales must remain public.
- Initialize the target runtime in a branch or separate directory.

### Files

- `docusaurus.config.js`
- `docusaurus.config.ts`
- `sidebars.js`
- `sidebars.ts`
- `docs.config.ts`
- `docs.config.tsx`

### Commands

- `npx @farming-labs/docs init` — Scaffold the target docs runtime before copying Docusaurus content.

### Side Effects

- Docusaurus navigation metadata and MDX components are rewritten for the target runtime.

### Verification

- Build the target and compare every published Docusaurus route, sidebar group, version, and asset.
  - Expected: Required routes resolve, the production build passes, and unsupported components are explicitly tracked.

### Rollback

- Keep the original Docusaurus deployment and restore the migration branch if route or version checks fail.

### Failure Modes

- MDX compilation fails on a Docusaurus import or JSX component. — Recovery: Replace the import with a Farming Labs component or preserve the component as a registered custom MDX component.
- A versioned URL no longer resolves. — Recovery: Copy that version into an explicit target path or add a redirect before cutover.
<!-- farming-labs:agent-contract:end -->

# From Docusaurus

## From Docusaurus task

Task: Migrate a Docusaurus documentation site into a supported Farming Labs Docs runtime.

Expected result: Docusaurus pages, sidebar order, assets, and supported MDX patterns render in a buildable Farming Labs Docs project.

## From Docusaurus prerequisites

- Preserve docusaurus.config, sidebars, docs, static, versions.json, versioned_docs, and versioned_sidebars.
- Decide which Docusaurus docs versions and locales must remain public.
- Initialize the target runtime in a branch or separate directory.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Docusaurus verification

- Build the target and compare every published Docusaurus route, sidebar group, version, and asset. Expected: Required routes resolve, the production build passes, and unsupported components are explicitly tracked.
- Failure: MDX compilation fails on a Docusaurus import or JSX component.
- Recovery: Replace the import with a Farming Labs component or preserve the component as a registered custom MDX component.
- Rollback: Keep the original Docusaurus deployment and restore the migration branch if route or version checks fail.

## From Docusaurus agent guidance

Inventory every active docs plugin instance, sidebar file, docs root, locale, and version before
moving content. Treat docusaurus.config and sidebars as executable input: do not copy them into
docs.config verbatim. Preserve published routes first, then translate components. Docusaurus blog,
pages, custom themes, and non-doc plugins are separate application migrations.

## 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).