VuePress vs VitePress: Which Should You Choose?

For almost every new Vue documentation site, choose VitePress.

If you have kept a VuePress 1 site alive recently, you know the tell: you save a Markdown file, then go find something else to do while webpack rebuilds. That gap is most of what this comparison comes down to.

VitePress is the static-site generator the Vue team officially recommends, VuePress 1 is deprecated, and VuePress 2 is community-maintained and still a release candidate. Pick VuePress 2 only when you specifically need something it still does better, such as a bespoke plugin/theme API or easier component swapping, and reach for a React-based generator like Docusaurus if you need first-party docs versioning.

This article justifies that call with the concrete differences that actually decide a docs project: project momentum, dev-loop speed, the customization tradeoff, and what VitePress genuinely can’t do yet. It also corrects the stale “VitePress is alpha” framing you’ll still find in older comparisons.

Which is actively maintained, VuePress or VitePress?

Project momentum is the single biggest input to this decision, and it points one way. VitePress picks up where VuePress left off, running the same Markdown-to-docs idea on Vue 3 and Vite. The Vue team concluded it could not keep two generators going at once and settled on VitePress as its recommended one, retiring VuePress 1 and passing VuePress 2 to a community team.

The maturity picture is the reverse of what older articles claim. VitePress is the stable one: npm still lists 1.6.4 as its latest release, and the changelog puts the next major line in alpha, at 2.0.0-alpha.19. The VuePress core repo still describes its own status as a release candidate, so VuePress 2 never reached a final stable release. VitePress also powers the docs for Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify, and the Vue.js site itself.

Dev experience: Vite versus webpack

The dev loop is where VitePress separates itself. VuePress 1 built on Vue 2 and webpack, which dated quickly; VitePress runs on Vue 3 and Vite. The official docs put the gap between saving a file and seeing the change on screen at under 100 milliseconds, with no page reload and no wait for the dev server to boot. That is a different class of feedback loop from a webpack rebuild.

Output architecture matters too. In development, the dev server runs on port 5173 unless you point it elsewhere. In production, the first page a visitor lands on is pre-rendered static HTML, which loads quickly and indexes well; VitePress then hydrates it into a Vue single-page app, so every navigation after that happens in the browser, as the 1.0 release post explains. VitePress also builds in local full-text search, one config option away, and Shiki, the same syntax highlighter VS Code uses, so neither needs wiring up by hand.

Configuration and customization: the real tradeoff

Here’s the honest tension. VitePress has a simpler config and a genuinely strong default theme, but deep customization means writing Vue. VitePress has no plugin system of its own by design: customization is delegated to Vue via custom themes and slots, and to Vite via its config and plugins. VuePress 2 keeps a broader, bespoke plugin/theme API and makes component-swapping in config more direct, which is why teams deep into a customized VuePress site sometimes stay put.

That design has practical edges. Overriding scoped styles inside the default theme’s Vue components occasionally forces an !important. The sidebar is much simpler and supports a separate sidebar per subfolder, but you write it out by hand in themeConfig.sidebar: a new Markdown file won’t appear until you edit the config or add a community plugin like vitepress-sidebar. Frontmatter is easy to read directly inside Markdown, and prev/next links are inferred from the sidebar unless you set prev and next yourself, which can point at any page, sidebar or not.

The VitePress sidebar config is clean:

// .vitepress/config.ts
export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        collapsed: true,
        items: [
          { text: 'Introduction', link: '/guide/' },
          { text: 'Getting Started', link: '/guide/getting-started' },
        ],
      },
    ],
  },
}

Use the object form keyed by path (sidebar: { '/guide/': [...] }) when you want a distinct sidebar per section. That is the multi-sidebar pattern VuePress makes harder.

When is VitePress the wrong pick?

VitePress is deliberately scoped, and a few gaps are real. It has no first-party docs versioning: teams maintaining v1/v2/v3 simultaneously keep separate version folders and wire up sidebars manually, which is the main reason to choose Docusaurus instead. Its plugin ecosystem is small next to Docusaurus. Its blog story is weak: no built-in tag system, RSS feed, or archive page, so a marketing-heavy site is more work than it’s worth. And it requires Vue the moment you go past Markdown and the default theme.

Pick VitePress unless you specifically need first-party versioning or a large plugin library, which is Docusaurus territory, or your stack is React, in which case Fumadocs, Nextra, or Docusaurus fit better.

Migrating from VuePress, and the final verdict

Scaffolding a new VitePress site is four commands: npm add -D vitepress, then npx vitepress init to run the setup wizard, npm run docs:dev for the local server, and npm run docs:build to emit static output to .vitepress/dist. The current official docs default their own install command to the 2.0-alpha line (vitepress@next) and list Node.js 22 or higher as a prerequisite, so plain npm add -D vitepress is what gets you the stable 1.x.

Migration from VuePress is not a drop-in. Your Markdown, frontmatter, and shared Markdown extensions carry over cleanly; the config schema, theme, and layout must be reworked, and any bespoke VuePress plugins need VitePress equivalents. Default-theme sites migrate most easily.

The decision rule: for a new Vue documentation site, choose VitePress and don’t look back. If you’re on a VuePress default-theme site, migrate to VitePress. If you need first-party versioning or a deep plugin library, weigh Docusaurus. And if your stack is React, start with a React-based generator instead. Install VitePress, run npx vitepress init, and you’ll have a working docs site before you’ve finished reading the config reference.

FAQs

Is VuePress deprecated?

VuePress 1 is deprecated and in maintenance mode, while VuePress 2 was handed to a community team and remains a release candidate that never shipped a final stable version. The Vue team decided maintaining two generators in parallel wasn't sustainable and now recommends VitePress as its main static-site generator. On npm, the VuePress core 'latest' tag still resolves to the 1.x line, reinforcing that 2.0 never left RC.

Can VitePress auto-generate the sidebar from my folder structure?

No. VitePress does not auto-generate the sidebar by default. A new Markdown file will not appear until you manually edit the sidebar in your config file or install a community plugin such as vitepress-sidebar. VitePress does support multiple sidebars keyed by path, so you can define a distinct sidebar per subfolder, but the mapping is explicit rather than derived from the directory tree.

Does VitePress support documentation versioning like Docusaurus?

No. VitePress has no built-in first-party versioning feature. Teams that maintain several docs versions simultaneously keep separate version folders and wire up their sidebars manually. If versioned documentation with dropdown switching is a hard requirement, Docusaurus is the stronger choice, since first-party versioning is one of its core features. This is the single most common reason to pick a React-based generator over VitePress.

Why does VitePress require writing Vue components for deep customization?

VitePress has no plugin system of its own by design. Instead of a bespoke plugin API, customization is delegated to Vue through custom themes and slots, and to Vite through its config and plugin ecosystem. This keeps the core minimal, but it means overriding the default theme's look or behavior involves writing Vue components and occasionally forcing scoped-style overrides with !important, rather than flipping configuration options.