---
title: "From VitePress"
description: "Migrate VitePress Markdown, sidebar configuration, Vue components, containers, and assets"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/vitepress"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/vitepress.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1650
  task: "Migrate a VitePress documentation site into Farming Labs Docs."
  outcome: "VitePress pages, navigation, assets, and portable Markdown render in a buildable Farming Labs Docs project, with Vue-only behavior explicitly replaced or tracked."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Preserve the VitePress root, .vitepress config and theme, public assets, Markdown pages, and custom Vue components."
    - "Record the published base path, rewrites, clean URL behavior, locales, and sidebar variants."
    - "Initialize the target runtime separately."
  files:
    - ".vitepress/config.ts"
    - ".vitepress/config.mts"
    - ".vitepress/theme/index.ts"
    - "docs.config.ts"
    - "docs.config.tsx"
  commands:
    - run: "npx @farming-labs/docs init"
      description: "Scaffold the selected target runtime before moving VitePress pages."
  sideEffects:
    - "Markdown-It extensions and Vue components may be rewritten as MDX, plain Markdown, or target-native components."
  verification:
    - description: "Build the target and compare routes, sidebar variants, containers, code groups, assets, locales, and redirects."
      expect: "Required routes resolve and no Vue-only syntax remains in content compiled by a non-Vue target."
  rollback:
    - "Keep the VitePress build and deployment available until the target route and component comparison passes."
  failureModes:
    - symptom: "MDX compilation fails on Vue template syntax."
      resolution: "Convert the block to portable Markdown or a component native to the selected target runtime."
    - symptom: "Published URLs gain or lose a base prefix."
      resolution: "Match the previous entry path or add tested redirects that include the old base."
---

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

Task: Migrate a VitePress documentation site into Farming Labs Docs.
Outcome: VitePress pages, navigation, assets, and portable Markdown render in a buildable Farming Labs Docs project, with Vue-only behavior explicitly replaced or tracked.

### Applies To

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

### Prerequisites

- Preserve the VitePress root, .vitepress config and theme, public assets, Markdown pages, and custom Vue components.
- Record the published base path, rewrites, clean URL behavior, locales, and sidebar variants.
- Initialize the target runtime separately.

### Files

- `.vitepress/config.ts`
- `.vitepress/config.mts`
- `.vitepress/theme/index.ts`
- `docs.config.ts`
- `docs.config.tsx`

### Commands

- `npx @farming-labs/docs init` — Scaffold the selected target runtime before moving VitePress pages.

### Side Effects

- Markdown-It extensions and Vue components may be rewritten as MDX, plain Markdown, or target-native components.

### Verification

- Build the target and compare routes, sidebar variants, containers, code groups, assets, locales, and redirects.
  - Expected: Required routes resolve and no Vue-only syntax remains in content compiled by a non-Vue target.

### Rollback

- Keep the VitePress build and deployment available until the target route and component comparison passes.

### Failure Modes

- MDX compilation fails on Vue template syntax. — Recovery: Convert the block to portable Markdown or a component native to the selected target runtime.
- Published URLs gain or lose a base prefix. — Recovery: Match the previous entry path or add tested redirects that include the old base.
<!-- farming-labs:agent-contract:end -->

# From VitePress

## From VitePress task

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

Expected result: VitePress pages, navigation, assets, and portable Markdown render in a buildable Farming Labs Docs project, with Vue-only behavior explicitly replaced or tracked.

## From VitePress prerequisites

- Preserve the VitePress root, .vitepress config and theme, public assets, Markdown pages, and custom Vue components.
- Record the published base path, rewrites, clean URL behavior, locales, and sidebar variants.
- Initialize the target runtime separately.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From VitePress verification

- Build the target and compare routes, sidebar variants, containers, code groups, assets, locales, and redirects. Expected: Required routes resolve and no Vue-only syntax remains in content compiled by a non-Vue target.
- Failure: MDX compilation fails on Vue template syntax.
- Recovery: Convert the block to portable Markdown or a component native to the selected target runtime.
- Rollback: Keep the VitePress build and deployment available until the target route and component comparison passes.

## From VitePress agent guidance

Read the resolved VitePress config, not only the root file: configuration can be async, split into
helpers, or overridden per directory. Inventory root, srcDir, base, rewrites, locales, themeConfig
nav and sidebar, markdown plugins, and theme enhancements before moving files.

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