VitePress : écrire une documentation technique qui charge en 100ms

J'ai testé trois générateurs de doc avant de m'arrêter sur VitePress : Docusaurus, GitBook, et VitePress. Docusaurus fait tout, mais son build ralentit dès que le nombre de pages grimpe, et la config React autour finit par peser plus lourd que le contenu lui-même. GitBook est propriétaire et pousse vers son cloud. VitePress fait une chose : transformer du Markdown en site statique rapide, avec juste assez de structure pour une doc technique sérieuse.

VitePress est construit par l'équipe Vue sur Vite. Chaque fichier .md devient une page. La navigation, la sidebar, la recherche et le mode sombre sont générés depuis un seul fichier de config. Pas de plugin à assembler pendant des heures — la valeur par défaut est déjà bonne.

Installation

npm add -D vitepress
npx vitepress init

L'assistant init pose quatre questions (dossier, titre, description, thème) et génère la structure de base :

docs/
├── .vitepress/
│   └── config.mts
├── index.md
└── guide/
    └── getting-started.md

npm run docs:dev    # serveur local avec hot reload
npm run docs:build  # build statique de production

Le dev server démarre en dessous de la seconde — c'est Vite, pas Webpack. Chaque sauvegarde de fichier Markdown se répercute instantanément dans le navigateur sans rechargement complet de la page.

Configuration : la sidebar et la nav

import { defineConfig } from 'vitepress'
 
export default defineConfig({
  title: 'Ma Documentation',
  description: 'Documentation technique du projet',
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/getting-started' },
      { text: 'API', link: '/api/' },
    ],
    sidebar: [
      {
        text: 'Démarrage',
        items: [
          { text: 'Installation', link: '/guide/getting-started' },
          { text: 'Configuration', link: '/guide/config' },
        ],
      },
    ],
    search: {
      provider: 'local',
    },
  },
})

search: { provider: 'local' } active une recherche full-text indexée au build, sans dépendance externe. Pour un site plus large, l'option algolia branche une recherche hébergée gratuite (programme DocSearch d'Algolia), mais local suffit largement jusqu'à plusieurs centaines de pages.

Markdown étendu

VitePress ajoute des extensions utiles au Markdown standard, pensées pour la doc technique :

::: warning
Cette fonctionnalité est expérimentale.
:::
 
::: tip
Utilisez `pnpm` plutôt que `npm` pour ce projet.
:::

Les blocs de code supportent la coloration ligne par ligne :

```ts{2,4}
function hello() {
  console.log('surligné')
  const x = 1
  return x // surligné aussi
}
```

Et l'inclusion de fragments de code depuis de vrais fichiers source, pour éviter que la doc et le code divergent :

<<< @/../src/utils.ts#exempleFonction

Ce dernier point change la donne sur un projet qui bouge vite : au lieu de copier-coller un snippet qui devient obsolète après trois refactors, la doc pointe vers le vrai fichier et affiche la section marquée par un commentaire #region.

Composants Vue dans le Markdown

Chaque fichier .md peut embarquer du Vue directement — utile pour une doc interactive (un composant de démo, un playground).

<script setup>
import Demo from '../components/Demo.vue'
</script>
 
# Ma page
 
Voici le composant en action :
 
<Demo />

Ça reste optionnel. Une doc purement Markdown fonctionne très bien sans jamais toucher à Vue — c'est juste disponible si le besoin apparaît.

Déploiement

Le build produit un dossier docs/.vitepress/dist — du HTML/CSS/JS statique, déployable n'importe où : Vercel, Netlify, GitHub Pages, ou un simple Nginx sur un VPS.

name: Deploy docs
on:
  push:
    branches: [main]
 
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist

Un push sur main rebuild et redéploie la doc automatiquement — le même principe que n'importe quel pipeline CI/CD.

VitePress vs Docusaurus vs Nextra

Docusaurus gagne si le projet a besoin de versioning de doc multi-version natif (plusieurs versions d'API en parallèle) — c'est sa killer feature. Pour une doc mono-version, un README de projet enrichi, ou la doc d'une lib open-source, VitePress fait le travail avec beaucoup moins de friction.

VitePress ne remplace pas un CMS pour du contenu éditorial complexe, et il assume clairement son terrain : la documentation technique. Pour ça, c'est l'outil qui demande le moins de configuration pour le meilleur résultat. Si le projet est déjà en Vue ou React, la cohérence d'écosystème avec Vue est un bonus, pas une contrainte — VitePress documente très bien des projets qui n'ont rien à voir avec Vue.