Migrating from VuePress

VuePress is an open-source static site generator built on Vue.

Key Similarities between VuePress and Astro

VuePress and Astro share some similarities that will help you migrate your project:

Both VuePress and Astro are modern Javascript static-site generators with similar project file structures. Both use a special src/pages/ folder for file-based routing. Creating and managing pages for your site should feel familiar.
Astro and VuePress are both designed for content-driven websites, with excellent built-in support for Markdown files. Writing in Markdown will feel familiar, and you will be able to keep your existing content.
Astro has an official integration for using Vue components and supports installing NPM packages, including several for Vue. You will be able to write Vue UI components, and may be able to keep some or all of your existing Vue components and dependencies.

Key Differences between VuePress and Astro

When you rebuild your VuePress site in Astro, you will notice some important differences.

VuePress is a Vue-based single-page application (SPA). Astro sites are multi-page apps built using .astro components, but can also support React, Preact, Vue.js, Svelte, SolidJS, AlpineJS and raw HTML templating.
Layout templates: VuePress sites are created using Markdown (.md) files for page content and HTML (.html) templates for layout. Astro is component-based, and uses Astro components, which include HTML templating for pages, layouts and individual UI elements. Astro can also create pages from .md and .mdx files, using an Astro layout component for wrapping Markdown content in a page template.
VuePress was designed to build content-heavy, Markdown-centric sites and has some built-in, documentation-specific website features that you would have to build yourself in Astro. Instead, Astro offers some documentation-specific features through an official docs theme. This website was the inspiration for that template! You can also find more community docs themes with built-in features in our Themes Showcase.

Switch from VuePress to Astro

To convert a VuePress documentation site to Astro, start with our official Starlight docs theme starter template, or explore more community docs themes in our theme showcase.

You can pass a --template argument to the create astro command to start a new Astro project with one of our official starters. Or, you can start a new project from any existing Astro repository on GitHub.

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

Bring your existing Markdown content files to create Markdown pages. You can still take advantage of file-based routing by moving these documents from docs in VuePress to src/pages/ in Astro. Create folders with names that correspond to your existing VuePress project, and you should be able to keep your existing URLs.

VuePress, or any theme you installed, probably handled much of your site layout and metadata for you. You may wish to read about building Astro Layouts as Markdown page wrappers to see how to manage templating yourself in Astro, including your page <head>.

You can find Astro’s docs starter, and other templates, on astro.new. You’ll find a link to each project’s GitHub repository, as well as one-click links to open a working project in IDX, StackBlitz, CodeSandbox and Gitpod online development environments.