Blume vs VitePress.Docs from your folders, not your config.
VitePress is the Vue team's fast static generator, with a sidebar you list in config and agent features left to community plugins. Blume builds the site from your folders, with llms.txt, an MCP server, API references, and versioning built in.
npx blume migrate vitepress --codex| Blume | VitePress | |
|---|---|---|
| You maintain | BlumeA folder of Markdown, plus one optional config file | VitePress.vitepress/config with a sidebar you list by hand, plus any theme code |
| Built on | BlumeAstro, generated and run for you | VitePressVite and Vue 3, with every page compiled as a Vue component |
| License | BlumeFree and open source (MIT) | VitePressFree and open source (MIT), maintained by the Vue team |
| Search | BlumeLocal search with no keys, or Pagefind, Algolia, and more by adapter | VitePressLocal MiniSearch built in, or Algolia DocSearch |
| Agent features | Blumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP server | VitePressllms.txt and Markdown pages through the community vitepress-plugin-llms; no official MCP server |
| API references | BlumeOpenAPI, AsyncAPI, and GraphQL, with a Try it playground | VitePressNot built in; OpenAPI through the community vitepress-openapi plugin |
| Versioning | Blumeblume version snapshots with a switcher and scoped search | VitePressNot built in; an open feature request since 2020 |
| Languages | Blumeblume translate fills in every locale with your coding agent | VitePressBuilt-in i18n with locale folders and a language switcher |
VitePress details are from its own pages as of October 7, 2026: What is VitePress, Search, Vue in Markdown, i18n, Versioning issue, Releases. Something out of date? Let us know
Your docs come with you.A codemod does the Markdown, and an agent does the rest.
- Containers become directives.
::: tipand::: warning Titlebecome:::tipand:::warning[Title], GitHub alerts become callouts, and code groups become CodeGroup.- Sidebars move into folders.
- Each sidebar becomes a header tab, and groups that existed only in config become
(group)folders, so no page URL changes. - Snippets become includes.
<<<snippet imports become<include>with their titles and highlighted lines, and so do<!--@include:-->partials.- Old URLs and anchors keep working.
- Every old
.htmlURL redirects to its page, and a script pins each heading's VitePress anchor so deep links still land.
VitePress
Blume
- .vitepress/config.tsblume.config.ts
- themeConfig.sidebarmeta.ts
- ::: tip Title:::tip[Title]
- ::: code-group<CodeGroup>
- ::: details<Expandable>
- <<< @/snippets/a.ts<include>
- /guide/setup.html/guide/setup
When VitePress might suit you better.Blume isn't the right fit for every team.
- You want Vue in every page.
- Every VitePress page compiles to a Vue component, so
{{ }}expressions, directives, and<script setup>work right in the Markdown. Blume pages are MDX, with Vue components as islands. - You want what Vue and Vite use.
- VitePress is maintained by the Vue team and runs the docs for Vue, Vite, Vitest, Rollup, and Pinia. Edits show in under 100ms in dev, and pages navigate instantly after the first load.
- You want to write the theme in Vue.
- A VitePress theme is a Vue layout you can extend or replace, and data loaders and dynamic routes generate pages at build time. Blume keeps the app hidden until you eject.
- 1
Run one command in your docs project.
Using Claude Code? Swap
--codexfor--claude. - 2
Review the agent's edits.
It follows Blume's migration playbook for MintlifyFumadocsDocusaurusStarlightNextraGitBookMkDocsReadMeVitePressFernRedoclyVuePressDocsifyDocusmdBookJekyllGitHub Wiki, rewriting your config and pages in place, so you review the whole move as one diff.
- 3
Preview the result.
Run
npx blume dev, then read the agent's summary of anything it dropped or approximated.
Questions, answered.About moving from VitePress to Blume.
Why switch from VitePress if both are free?
Because VitePress leaves the docs features to you. You list every sidebar page in config, llms.txt and API references come from community plugins, and versioning isn't built in. Blume builds navigation from your folders and ships all of those built in.
Can I keep my VitePress Markdown?
Yes. npx blume migrate vitepress --codex runs a codemod that converts containers, code groups, alerts, snippet imports, and badges, and renames pages that need MDX to .mdx. The agent then handles what's left, like Vue syntax and components, and redirects every old .html URL.
Can I keep my Vue components?
Yes, as islands. Put the .vue file in islands/, install @astrojs/vue and vue, and use it in any .mdx page. A component that imports from vitepress, like useData(), doesn't run outside it, so the agent reports it for you to rewrite or drop.
Is VitePress 2 stable?
Not yet. The latest stable release is 1.6.4, from August 2025, and 2.0 has been in alpha since January 2025, with alpha.20 in September 2026. VitePress's own docs now install it with vitepress@next.
What doesn't the migration carry over?
The Vue app around your Markdown: custom theme code, layout slots, data loaders, and dynamic routes become static content, Blume components, or islands. Vite and custom markdown-it plugins, titleTemplate, the footer message, and your DocSearch index don't carry over, and the agent reports each one.
Upgrade your docs with Blume.
Install today and ship a production-grade docs site in minutes. Free and open source, forever.
npx blume init