Migrate from VitePressCopy Anchor Link

VitePress content is Markdown, but it is parsed by Markdown-It and can embed Vue templates and components. Plain pages move easily; custom containers, code groups, theme slots, and Vue behavior need explicit conversion.

1. Inventory the sourceCopy Anchor Link

Record:

• the VitePress root and optional srcDir
• .vitepress/config.* and imported config helpers
• .vitepress/theme/, globally registered components, and custom CSS
• themeConfig.nav and every themeConfig.sidebar variant
• base, cleanUrls, rewrites, and locale configuration
• Markdown-It plugins and custom containers
• public/, relative assets, and imported images
• search, sitemap, analytics, head tags, and deployment settings

2. Map the filesCopy Anchor Link

3. Preserve routingCopy Anchor Link

VitePress routes depend on the content root, srcDir, base, clean URLs, and rewrites. Build a source route list before moving files.

For each page:

• preserve the URL path through the destination file structure
• keep title, description, and portable frontmatter
• preserve explicit heading IDs used by external links
• include the old base prefix in the target entry or redirect it
• convert rewrites into actual destination paths or redirects

Do not assume a file's repository path equals its published path.

4. Rebuild nav and sidebarCopy Anchor Link

VitePress top navigation and sidebars are separate:

1. Translate themeConfig.nav into the target application's top navigation.
2. Turn sidebar groups into directories and folder landing pages.
3. Preserve item order with numeric order frontmatter.
4. Recreate per-path sidebar objects as separate content sections.
5. Preserve collapsed/expanded intent where the target sidebar supports it.
6. Keep external links explicit.

Generated sidebar functions should be evaluated into a stable inventory before migration.

5. Convert Markdown extensionsCopy Anchor Link

Check code fences carefully because VitePress uses its own highlight and line-focus notation.

6. Replace Vue components and theme behaviorCopy Anchor Link

Search pages for:

• .vue imports
• globally registered component tags
• Vue directives such as v-if, v-for, and v-bind
• mustache interpolation
• <script setup>
• theme slots and layout overrides

For an Astro or Svelte target, rewrite them as native components. For Next.js or TanStack Start, rewrite interactive blocks as React components. For static behavior, prefer plain Markdown.

7. Move assets and integrationsCopy Anchor Link

Copy public/ to the target public/static directory and keep root-relative URLs stable. Verify assets imported from Markdown or Vue components separately.

Recreate search, analytics, sitemap, social metadata, edit links, last-updated behavior, and deployment base settings through Farming Labs and the target application.

8. Validate and recoverCopy Anchor Link

1. Run the target production build.
2. Compare routes after applying the old base and rewrites.
3. Test custom containers, code groups, heading anchors, and code highlights.
4. Inspect pages containing Vue imports or directives.
5. Compare each sidebar variant and locale.
6. Fetch representative pages through .md.

If compilation fails, locate the first remaining Vue or Markdown-It-only construct and convert that family across the corpus. If links fail, compare against the resolved VitePress route—not only the source filename.

Source referencesCopy Anchor Link

• VitePress site configuration
• VitePress sidebar
• VitePress Markdown extensions
• Farming Labs sidebar
• Farming Labs components