Migrate from DocusaurusCopy Anchor Link

Docusaurus is already Markdown- and MDX-based, so most prose, headings, code fences, and local assets can move directly. The main work is translating sidebars, Docusaurus-only components, versioned routes, and plugin behavior.

1. Inventory the sourceCopy Anchor Link

Record these inputs before editing:

• docusaurus.config.js, .ts, .mjs, or .mts
• sidebars.js, .ts, or generated sidebar definitions
• every @docusaurus/plugin-content-docs instance and its path and routeBasePath
• docs/, static/, src/components/, and src/css/
• versions.json, versioned_docs/, and versioned_sidebars/
• locale folders under i18n/
• redirects, Algolia, analytics, OpenAPI, and custom plugins

2. Map the filesCopy Anchor Link

For Next.js, each migrated route uses app/docs/**/page.mdx or src/app/docs/**/page.mdx. The other adapters read Markdown or MDX from the configured contentDir.

3. Preserve slugs and frontmatterCopy Anchor Link

Docusaurus commonly derives a route from id, slug, the filename, and the plugin route base. Build a route list before moving files. Keep these fields when they still describe content:

• title
• description
• sidebar_label → title when it is the preferred navigation label
• sidebar_position → order
• tags
• explicit slug, represented by the destination file path whenever possible

Review Docusaurus-only fields such as pagination_next, pagination_prev, toc_min_heading_level, toc_max_heading_level, hide_table_of_contents, and draft. Recreate the desired behavior in Farming Labs config or remove the field intentionally.

4. Translate sidebarsCopy Anchor Link

Farming Labs Docs builds its default sidebar from the content tree. Recreate each Docusaurus category as a directory and give pages numeric order values matching the source order.

docs/
├── getting-started/
│   ├── index.mdx
│   ├── installation.mdx
│   └── configuration.mdx
└── reference/
    └── api.mdx

Use folder landing pages for category introductions. External sidebar links belong in the application navigation or a custom sidebar. Generated and dynamic sidebar functions require an explicit snapshot or an equivalent custom navigation implementation.

5. Convert Docusaurus MDXCopy Anchor Link

Remove Docusaurus imports only after replacing every corresponding JSX use. For a custom component that should survive, register it under components in docs.config.ts.

6. Handle versions and localesCopy Anchor Link

Docusaurus stores frozen versions in versioned_docs/version-<name>/ and matching navigation in versioned_sidebars/. Choose one policy:

1. Current only: migrate docs/ and redirect or archive older versions.
2. Supported versions: place each maintained version under an explicit route such as /docs/v2/....
3. Separate deployments: keep old Docusaurus versions online while new documentation moves.

Do not silently collapse multiple versions into one route. Apply the same explicit decision to each locale under i18n/.

7. Recreate integrationsCopy Anchor Link

Translate these independently from content:

• Algolia or another search provider → search
• OpenAPI plugins → apiReference
• redirects → target host/runtime redirects
• analytics → analytics or the target provider
• custom head tags → application metadata
• authentication → application middleware plus opt-in agent endpoint authentication

Docusaurus blog, custom React pages, and plugin-generated application routes are outside the docs content migration and should have their own owner.

8. Validate and recoverCopy Anchor Link

1. Run the target production build.
2. Compare the source and target route lists, including version and locale prefixes.
3. Open pages containing tabs, admonitions, imported components, diagrams, and relative images.
4. Check sidebar order, collapsed groups, previous/next links, and mobile navigation.
5. Fetch several migrated pages through their .md routes.
6. Keep redirects and the source deployment until production traffic is verified.

If compilation fails, isolate the first source-only import and replace it before continuing. If a route changes, prefer restoring the old path; otherwise add a permanent redirect and test its destination.

Source referencesCopy Anchor Link

• Docusaurus docs configuration
• Docusaurus sidebars
• Docusaurus versioning
• Farming Labs components
• Farming Labs configuration