Skip to content

Migrating from VuePress

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

Key Similarities between VuePress and Astro

Section titled Key Similarities between VuePress and Astro

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

Key Differences between VuePress and Astro

Section titled 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, Lit 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.

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.

Terminal window
npm create astro@latest -- --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 You’ll find a link to each project’s GitHub repository, as well as one-click links to open a working project in StackBlitz, CodeSandbox and Gitpod online development environments.

  • Add your own!

More migration guides