VuePress vs VitePress : lequel choisir ?

Pour presque tous les nouveaux sites de documentation Vue, choisissez VitePress.

Si vous avez maintenu un site VuePress 1 en vie récemment, vous connaissez le symptôme : vous enregistrez un fichier Markdown, puis vous partez faire autre chose pendant que webpack reconstruit. C’est essentiellement à cet écart que se résume cette comparaison.

VitePress est le générateur de sites statiques officiellement recommandé par l’équipe Vue, VuePress 1 est déprécié, et VuePress 2 est maintenu par la communauté tout en restant en release candidate. Ne choisissez VuePress 2 que si vous avez spécifiquement besoin de ce qu’il fait encore mieux, comme une API de plugins/thèmes sur mesure ou une substitution de composants plus simple, et tournez-vous vers un générateur basé sur React comme Docusaurus si vous avez besoin d’un versionnement de documentation natif.

Cet article justifie ce choix par les différences concrètes qui déterminent réellement un projet de documentation : la dynamique du projet, la vitesse de la boucle de développement, le compromis sur la personnalisation, et ce que VitePress ne sait véritablement pas encore faire. Il corrige également le discours obsolète du « VitePress est en alpha » que l’on trouve encore dans les comparaisons anciennes.

Lequel est activement maintenu, VuePress ou VitePress ?

La dynamique du projet est le facteur le plus déterminant de cette décision, et elle ne pointe que dans une direction. VitePress reprend là où VuePress s’est arrêté, en appliquant la même idée « du Markdown à la documentation » sur Vue 3 et Vite. L’équipe Vue a conclu qu’elle ne pouvait pas faire vivre deux générateurs en parallèle et a retenu VitePress comme son générateur recommandé, mettant VuePress 1 à la retraite et confiant VuePress 2 à une équipe communautaire.

Le tableau de la maturité est l’inverse de ce que prétendent les articles plus anciens. C’est VitePress qui est stable : npm indique toujours la 1.6.4 comme dernière version, et le changelog place la prochaine branche majeure en alpha, à 2.0.0-alpha.19. Le dépôt principal de VuePress décrit toujours son propre statut comme release candidate : VuePress 2 n’a donc jamais atteint de version stable finale. VitePress fait également tourner la documentation de Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify, ainsi que le site Vue.js lui-même.

Expérience de développement : Vite face à webpack

C’est sur la boucle de développement que VitePress se démarque. VuePress 1 s’appuyait sur Vue 2 et webpack, ce qui a rapidement vieilli ; VitePress tourne sur Vue 3 et Vite. La documentation officielle situe l’écart entre l’enregistrement d’un fichier et l’affichage de la modification à l’écran sous les 100 millisecondes, sans rechargement de page ni attente du démarrage du serveur de développement. C’est une boucle de rétroaction d’une toute autre catégorie qu’une reconstruction webpack.

L’architecture de sortie compte aussi. En développement, le serveur de dev tourne sur le port 5173 sauf si vous le déplacez ailleurs. En production, la première page sur laquelle arrive un visiteur est du HTML statique pré-rendu, qui se charge vite et s’indexe bien ; VitePress l’hydrate ensuite en application Vue monopage, de sorte que toutes les navigations suivantes se déroulent dans le navigateur, comme l’explique l’annonce de la version 1.0. VitePress intègre également une recherche plein texte locale, à une option de configuration près, et Shiki, le même moteur de coloration syntaxique que celui de VS Code : ni l’un ni l’autre ne nécessite de câblage manuel.

Configuration et personnalisation : le vrai compromis

Voici la tension, en toute honnêteté. VitePress offre une configuration plus simple et un thème par défaut véritablement solide, mais une personnalisation poussée implique d’écrire du Vue. VitePress n’a volontairement aucun système de plugins propre : la personnalisation est déléguée à Vue via les thèmes personnalisés et les slots, et à Vite via sa configuration et ses plugins. VuePress 2 conserve une API de plugins/thèmes plus large et sur mesure, et rend la substitution de composants plus directe dans la configuration — c’est pourquoi les équipes très investies dans un site VuePress fortement personnalisé restent parfois en place.

Ce choix de conception a des conséquences concrètes. Surcharger les styles scoped à l’intérieur des composants Vue du thème par défaut impose de temps en temps un !important. La sidebar est beaucoup plus simple et prend en charge une sidebar distincte par sous-dossier, mais vous la déclarez à la main dans themeConfig.sidebar : un nouveau fichier Markdown n’apparaîtra pas tant que vous n’aurez pas modifié la configuration ou ajouté un plugin communautaire comme vitepress-sidebar. Le frontmatter se lit facilement directement dans le Markdown, et les liens précédent/suivant sont déduits de la sidebar, sauf si vous définissez vous-même prev et next, qui peuvent pointer vers n’importe quelle page, présente ou non dans la sidebar.

La configuration de la sidebar VitePress est limpide :

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

Utilisez la forme objet indexée par chemin (sidebar: { '/guide/': [...] }) lorsque vous voulez une sidebar distincte par section. C’est le motif multi-sidebars que VuePress rend plus difficile.

Quand VitePress est-il le mauvais choix ?

VitePress a un périmètre délibérément restreint, et certaines lacunes sont réelles. Il n’offre aucun versionnement de documentation natif : les équipes qui maintiennent simultanément une v1/v2/v3 conservent des dossiers de version séparés et câblent les sidebars manuellement, ce qui est la principale raison de préférer Docusaurus. Son écosystème de plugins est restreint à côté de celui de Docusaurus. Son volet blog est faible : pas de système de tags intégré, ni de flux RSS, ni de page d’archives — un site à forte orientation marketing représente donc plus de travail que de bénéfice. Et il exige Vue dès l’instant où vous dépassez le Markdown et le thème par défaut.

Choisissez VitePress, sauf si vous avez spécifiquement besoin d’un versionnement natif ou d’une vaste bibliothèque de plugins — le territoire de Docusaurus — ou si votre stack est en React, cas dans lequel Fumadocs, Nextra ou Docusaurus conviennent mieux.

Migrer depuis VuePress, et le verdict final

Créer l’échafaudage d’un nouveau site VitePress tient en quatre commandes : npm add -D vitepress, puis npx vitepress init pour lancer l’assistant de configuration, npm run docs:dev pour le serveur local, et npm run docs:build pour générer la sortie statique dans .vitepress/dist. La documentation officielle actuelle fait pointer par défaut sa propre commande d’installation vers la branche 2.0-alpha (vitepress@next) et indique Node.js 22 ou supérieur comme prérequis : c’est donc un simple npm add -D vitepress qui vous donne la 1.x stable.

La migration depuis VuePress n’est pas un remplacement transparent. Votre Markdown, votre frontmatter et les extensions Markdown communes se transposent proprement ; le schéma de configuration, le thème et la mise en page doivent être retravaillés, et tout plugin VuePress sur mesure requiert un équivalent VitePress. Ce sont les sites utilisant le thème par défaut qui migrent le plus facilement.

La règle de décision : pour un nouveau site de documentation Vue, choisissez VitePress et n’y revenez pas. Si vous êtes sur un site VuePress avec le thème par défaut, migrez vers VitePress. Si vous avez besoin d’un versionnement natif ou d’une bibliothèque de plugins étoffée, évaluez Docusaurus. Et si votre stack est en React, partez plutôt d’un générateur basé sur React. Installez VitePress, lancez npx vitepress init, et vous aurez un site de documentation fonctionnel avant même d’avoir fini de lire la référence de configuration.

FAQ

VuePress est-il déprécié ?

VuePress 1 est déprécié et en mode maintenance, tandis que VuePress 2 a été confié à une équipe communautaire et reste une release candidate qui n'a jamais livré de version stable finale. L'équipe Vue a estimé que maintenir deux générateurs en parallèle n'était pas tenable et recommande désormais VitePress comme générateur de sites statiques principal. Sur npm, le tag 'latest' du cœur de VuePress renvoie toujours vers la branche 1.x, ce qui confirme que la 2.0 n'est jamais sortie du stade RC.

VitePress peut-il générer automatiquement la sidebar à partir de mon arborescence de dossiers ?

Non. VitePress ne génère pas automatiquement la sidebar par défaut. Un nouveau fichier Markdown n'apparaîtra pas tant que vous n'aurez pas modifié manuellement la sidebar dans votre fichier de configuration ou installé un plugin communautaire tel que vitepress-sidebar. VitePress prend bien en charge plusieurs sidebars indexées par chemin, ce qui permet de définir une sidebar distincte par sous-dossier, mais la correspondance est explicite plutôt que déduite de l'arborescence de répertoires.

VitePress prend-il en charge le versionnement de la documentation comme Docusaurus ?

Non. VitePress n'intègre aucune fonctionnalité de versionnement natif. Les équipes qui maintiennent plusieurs versions de documentation en parallèle conservent des dossiers de version séparés et câblent leurs sidebars manuellement. Si une documentation versionnée avec sélecteur déroulant est une exigence incontournable, Docusaurus est le choix le plus solide, puisque le versionnement natif fait partie de ses fonctionnalités centrales. C'est de loin la raison la plus fréquente de préférer un générateur basé sur React à VitePress.

Pourquoi VitePress exige-t-il d'écrire des composants Vue pour une personnalisation poussée ?

VitePress n'a volontairement aucun système de plugins propre. Au lieu d'une API de plugins sur mesure, la personnalisation est déléguée à Vue via les thèmes personnalisés et les slots, et à Vite via sa configuration et son écosystème de plugins. Cela maintient un cœur minimal, mais cela signifie que surcharger l'apparence ou le comportement du thème par défaut passe par l'écriture de composants Vue et, à l'occasion, par des surcharges de styles scoped forcées avec !important, plutôt que par le basculement d'options de configuration.