VuePress vs. VitePress: ¿cuál deberías elegir?

Para prácticamente cualquier sitio nuevo de documentación en Vue, elige VitePress.

Si últimamente has mantenido con vida un sitio en VuePress 1, ya conoces la señal: guardas un archivo Markdown y te vas a hacer otra cosa mientras webpack reconstruye. Esa espera es, en buena medida, de lo que trata esta comparación.

VitePress es el generador de sitios estáticos que el equipo de Vue recomienda oficialmente, VuePress 1 está obsoleto y VuePress 2 lo mantiene la comunidad y sigue siendo una release candidate. Elige VuePress 2 solo cuando necesites específicamente algo que aún hace mejor, como una API de plugins/temas a medida o un intercambio de componentes más sencillo, y recurre a un generador basado en React como Docusaurus si necesitas versionado de documentación nativo.

Este artículo justifica esa recomendación con las diferencias concretas que realmente deciden un proyecto de documentación: el impulso del proyecto, la velocidad del ciclo de desarrollo, el compromiso en materia de personalización y lo que VitePress realmente todavía no puede hacer. También corrige el planteamiento desactualizado de que “VitePress está en alpha” que todavía encontrarás en comparaciones antiguas.

¿Cuál se mantiene activamente, VuePress o VitePress?

El impulso del proyecto es el factor más determinante de esta decisión, y apunta en una sola dirección. VitePress retoma donde lo dejó VuePress, aplicando la misma idea de Markdown-a-documentación sobre Vue 3 y Vite. El equipo de Vue concluyó que no podía mantener dos generadores a la vez y se decantó por VitePress como el recomendado, retirando VuePress 1 y traspasando VuePress 2 a un equipo comunitario.

El panorama de madurez es justo el contrario al que afirman los artículos más antiguos. VitePress es el estable: npm sigue listando 1.6.4 como su última versión, y el changelog sitúa la siguiente línea mayor en alpha, en 2.0.0-alpha.19. El repositorio core de VuePress todavía describe su propio estado como release candidate, de modo que VuePress 2 nunca alcanzó una versión estable final. VitePress también impulsa la documentación de Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify y el propio sitio de Vue.js.

Experiencia de desarrollo: Vite frente a webpack

El ciclo de desarrollo es donde VitePress marca la diferencia. VuePress 1 se construyó sobre Vue 2 y webpack, algo que quedó desfasado con rapidez; VitePress funciona con Vue 3 y Vite. La documentación oficial sitúa el intervalo entre guardar un archivo y ver el cambio en pantalla por debajo de los 100 milisegundos, sin recarga de página y sin esperar a que arranque el servidor de desarrollo. Eso es una categoría de ciclo de retroalimentación completamente distinta a una reconstrucción con webpack.

La arquitectura de salida también importa. En desarrollo, el servidor de desarrollo se ejecuta en el puerto 5173 salvo que lo apuntes a otro sitio. En producción, la primera página a la que llega un visitante es HTML estático prerrenderizado, que carga rápido y se indexa bien; VitePress la hidrata después en una single-page app de Vue, de modo que toda navegación posterior ocurre en el navegador, tal y como explica el anuncio de la versión 1.0. VitePress también integra búsqueda local de texto completo, a una opción de configuración de distancia, y Shiki, el mismo resaltador de sintaxis que usa VS Code, así que ninguno de los dos requiere configuración manual.

Configuración y personalización: el verdadero compromiso

Aquí está la tensión, sin rodeos. VitePress tiene una configuración más sencilla y un tema por defecto realmente sólido, pero la personalización profunda implica escribir Vue. VitePress no tiene un sistema de plugins propio por diseño: la personalización se delega en Vue mediante temas personalizados y slots, y en Vite mediante su configuración y sus plugins. VuePress 2 conserva una API de plugins/temas más amplia y a medida, y hace más directo el intercambio de componentes desde la configuración, razón por la cual los equipos con un sitio VuePress muy personalizado a veces se quedan donde están.

Ese diseño tiene aristas prácticas. Sobrescribir estilos con scope dentro de los componentes Vue del tema por defecto obliga de vez en cuando a recurrir a un !important. La barra lateral es mucho más simple y admite una barra lateral distinta por subcarpeta, pero la escribes a mano en themeConfig.sidebar: un nuevo archivo Markdown no aparecerá hasta que edites la configuración o añadas un plugin de la comunidad como vitepress-sidebar. El frontmatter es fácil de leer directamente dentro del Markdown, y los enlaces prev/next se infieren de la barra lateral salvo que definas prev y next tú mismo, que pueden apuntar a cualquier página, esté o no en la barra lateral.

La configuración de la barra lateral de VitePress es limpia:

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

Usa la forma de objeto indexada por ruta (sidebar: { '/guide/': [...] }) cuando quieras una barra lateral distinta por sección. Ese es el patrón de múltiples barras laterales que VuePress complica más.

¿Cuándo es VitePress la elección equivocada?

VitePress tiene un alcance deliberadamente acotado, y algunas carencias son reales. No tiene versionado de documentación nativo: los equipos que mantienen v1/v2/v3 simultáneamente conservan carpetas de versión separadas y configuran las barras laterales a mano, que es la principal razón para elegir Docusaurus en su lugar. Su ecosistema de plugins es pequeño comparado con el de Docusaurus. Su soporte para blogs es flojo: no hay sistema de etiquetas integrado, ni feed RSS, ni página de archivo, así que un sitio con fuerte orientación de marketing supone más trabajo del que vale. Y requiere Vue en cuanto vas más allá de Markdown y del tema por defecto.

Elige VitePress salvo que necesites específicamente versionado nativo o una biblioteca de plugins amplia, que es terreno de Docusaurus, o que tu stack sea React, en cuyo caso Fumadocs, Nextra o Docusaurus encajan mejor.

Migrar desde VuePress y el veredicto final

Levantar un sitio nuevo con VitePress son cuatro comandos: npm add -D vitepress, luego npx vitepress init para ejecutar el asistente de configuración, npm run docs:dev para el servidor local y npm run docs:build para generar la salida estática en .vitepress/dist. La documentación oficial actual establece por defecto en su propio comando de instalación la línea 2.0-alpha (vitepress@next) e indica Node.js 22 o superior como requisito, así que un simple npm add -D vitepress es lo que te da la 1.x estable.

La migración desde VuePress no es un reemplazo directo. Tu Markdown, el frontmatter y las extensiones de Markdown compartidas se trasladan sin problemas; el esquema de configuración, el tema y el layout hay que rehacerlos, y cualquier plugin a medida de VuePress necesita su equivalente en VitePress. Los sitios con el tema por defecto son los que migran con mayor facilidad.

La regla de decisión: para un sitio nuevo de documentación en Vue, elige VitePress y no mires atrás. Si tienes un sitio VuePress con el tema por defecto, migra a VitePress. Si necesitas versionado nativo o una biblioteca de plugins extensa, valora Docusaurus. Y si tu stack es React, empieza directamente con un generador basado en React. Instala VitePress, ejecuta npx vitepress init y tendrás un sitio de documentación funcionando antes de terminar de leer la referencia de configuración.

Preguntas frecuentes

¿Está obsoleto VuePress?

VuePress 1 está obsoleto y en modo mantenimiento, mientras que VuePress 2 se traspasó a un equipo comunitario y sigue siendo una release candidate que nunca publicó una versión estable final. El equipo de Vue decidió que mantener dos generadores en paralelo no era sostenible y ahora recomienda VitePress como su generador de sitios estáticos principal. En npm, la etiqueta 'latest' del core de VuePress todavía resuelve a la línea 1.x, lo que refuerza que la 2.0 nunca salió de RC.

¿Puede VitePress autogenerar la barra lateral a partir de mi estructura de carpetas?

No. VitePress no autogenera la barra lateral por defecto. Un nuevo archivo Markdown no aparecerá hasta que edites manualmente la barra lateral en tu archivo de configuración o instales un plugin de la comunidad como vitepress-sidebar. VitePress sí admite múltiples barras laterales indexadas por ruta, de modo que puedes definir una barra lateral distinta por subcarpeta, pero el mapeo es explícito en lugar de derivarse del árbol de directorios.

¿Admite VitePress el versionado de documentación como Docusaurus?

No. VitePress no tiene una función de versionado nativa integrada. Los equipos que mantienen varias versiones de documentación simultáneamente conservan carpetas de versión separadas y configuran sus barras laterales a mano. Si la documentación versionada con cambio mediante desplegable es un requisito ineludible, Docusaurus es la opción más sólida, ya que el versionado nativo es una de sus funcionalidades centrales. Esta es, con diferencia, la razón más habitual para elegir un generador basado en React en lugar de VitePress.

¿Por qué VitePress exige escribir componentes Vue para una personalización profunda?

VitePress no tiene un sistema de plugins propio por diseño. En lugar de una API de plugins a medida, la personalización se delega en Vue a través de temas personalizados y slots, y en Vite a través de su configuración y su ecosistema de plugins. Esto mantiene el núcleo mínimo, pero implica que sobrescribir el aspecto o el comportamiento del tema por defecto pasa por escribir componentes Vue y, en ocasiones, forzar la sobrescritura de estilos con scope mediante !important, en vez de activar opciones de configuración.