Créer et lancer un projet VitePress avec ServBay

VitePress est un générateur de sites statiques moderne, propulsé par Vue, conçu pour créer des sites de documentation rapides, élégants et faciles à maintenir. Basé sur Vite, il offre une expérience de développement exceptionnelle ainsi que des performances de build remarquables. Pour les développeurs souhaitant créer une documentation professionnelle pour leurs projets, bibliothèques ou produits, VitePress est un excellent choix.

Pour développer et tester VitePress en local, il est essentiel de disposer d’un environnement de développement web local stable et facile à configurer. ServBay répond parfaitement à ce besoin : il intègre plusieurs versions de Node.js et de puissants serveurs web (tels que Caddy ou Nginx), facilitant la mise en ligne de votre projet VitePress.

Ce guide vous explique comment exploiter l’environnement intégré de ServBay pour créer, configurer et lancer un projet VitePress, depuis zéro. Nous aborderons la mise en place du reverse proxy pour le serveur de développement et le service de fichiers statiques pour la production.

Qu’est-ce que VitePress ?

VitePress est un générateur de sites statiques (SSG) basé sur Vite, qui s’appuie sur la puissance de Vue 3 et la rapidité de Vite pour produire des sites web statiques. Il excelle particulièrement dans la création de documentation technique.

Principales caractéristiques et avantages de VitePress

• Expérience de développement ultra-rapide : Grâce au hot module replacement (HMR) de Vite, toute modification de contenu est instantanément visible dans le navigateur, maximisant ainsi la productivité.
• Propulsé par Vue : Permet l’utilisation directe de composants Vue au sein des fichiers Markdown, renforçant l’interactivité et la richesse de la documentation.
• Simplicité d’utilisation : Configuration minimale, prêt à l’emploi, se concentre sur la création de contenu.
• Haute performance : Des fichiers statiques générés légers et rapidement chargés, couplés à un routing client fluide d’application monopage.
• Optimisé pour le SEO : Structure HTML adaptée au référencement, prise en charge des balises personnalisées d’en-tête.
• Markdown enrichi : Prise en charge complète de CommonMark, GitHub Flavored Markdown (GFM) ainsi que d’autres extensions syntaxiques.

Avec VitePress, il est facile de concevoir des sites de documentation techniquement aboutis et performants.

Créer et lancer un projet VitePress avec ServBay

ServBay propose une gestion pratique des versions de Node.js, et permet de configurer le serveur web pour votre projet VitePress, que ce soit en mode développement ou production.

Prérequis

Avant de commencer, assurez-vous d’avoir :

1. Installé ServBay : ServBay doit être installé avec succès sur votre système macOS. Si ce n’est pas le cas, suivez le guide d’installation de ServBay.
2. Installé le package Node.js : Vérifiez dans ServBay que la version nécessaire de Node.js est installée et activée via l’onglet "Packages". Voir Utiliser Node.js.

Créer un projet VitePress

1. Initialiser le répertoire du projet

   Ouvrez le terminal. Il est conseillé de créer le dossier du projet sous le répertoire racine par défaut de ServBay /Applications/ServBay/www, afin de faciliter la configuration ultérieure dans ServBay.

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Installer VitePress et initialiser la configuration

   Dans le dossier servbay-vitepress-app, installez VitePress en tant que dépendance de développement et lancez la commande d’initialisation avec npm ou yarn.

   npm add -D vitepress
   npx vitepress init

   Ou avec Yarn :

   yarn add -D vitepress
   yarn vitepress init

   La commande d’initialisation vous guidera dans les réglages de base : titre du site, description, etc. Suivez les instructions à l’écran :

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Répertoire des documents par défaut, validez avec Entrée
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Saisissez le titre de votre site, par exemple ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Saisissez la description du site
    │
    ◇  Theme:
    │  Default Theme # Choisissez le thème, par défaut cela convient
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Utiliser TypeScript pour la configuration ? À votre convenance
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Ajouter les scripts dans package.json ? Oui recommandé
    │
    └  Done! Now run npm run docs:dev and start writing.

   Après initialisation, un dossier docs sera créé, avec les fichiers de configuration par défaut (.vitepress) et des exemples de pages (index.md, guide/index.md, etc.), ainsi qu’une mise à jour du package.json pour inclure les scripts de build et de développement VitePress.

Modifier le contenu du projet VitePress

1. Éditer la page d’accueil

   Le fichier d’accueil par défaut se situe dans docs/index.md. Ouvrez-le dans l’éditeur de texte de votre choix, par exemple :

   # Hello ServBay!
   
   Bienvenue sur votre site de documentation VitePress propulsé par ServBay.
   
   Ceci est un site de démonstration local construit avec VitePress et servi via ServBay.

Passer en mode développement

Lors du développement, il est courant d’utiliser le serveur de développement intégré de VitePress, qui propose le rechargement à chaud pour un aperçu en temps réel. Servez ensuite ce serveur à travers un domaine personnalisé en reverse proxy grâce à ServBay, tout en bénéficiant du SSL automatique.

1. Lancer le serveur de développement VitePress

   Dans le terminal, assurez-vous d’être dans /Applications/ServBay/www/servbay-vitepress-app et exécutez :

   npm run docs:dev -- --port 8585

   Ou avec Yarn :

   yarn docs:dev --port 8585

   Le serveur écoute alors sur le port choisi (par exemple 8585), typiquement accessible via http://localhost:8585.

2. Configurer le site (reverse proxy) dans ServBay

   Ouvrez le panneau ServBay, allez dans l’onglet "Sites" et ajoutez une nouvelle configuration :

   • Nom : Choisissez par exemple Site VitePress Développement.
   • Domaine : Utilisez un domaine local, par exemple vitepress-dev.servbay.demo (.servbay.demo est recommandé pour éviter toute collision).
   • Type de site : Sélectionnez Reverse Proxy.
   • IP : Saisissez 127.0.0.1.
   • Port : Renseignez le port défini précédemment, par exemple 8585.

   Enregistrez et appliquez. ServBay va configurer automatiquement le serveur web (Caddy ou Nginx) pour rediriger toute requête sur https://vitepress-dev.servbay.demo vers http://127.0.0.1:8585.

3. Accéder au site de développement

   Rendez-vous dans votre navigateur sur https://vitepress-dev.servbay.demo : votre site VitePress est servi par le serveur de développement, via un domaine personnalisé et un certificat SSL interne généré par ServBay User CA.

Construire la version de production

Une fois la documentation prête, il faut générer la version optimisée statique.

1. Générer la version de production

   Dans le terminal, depuis /Applications/ServBay/www/servbay-vitepress-app :

   npm run docs:build

   Ou avec Yarn :

   yarn docs:build

   Cette étape convertit vos fichiers Markdown, composants Vue, etc., en fichiers HTML, CSS, JavaScript statiques dans docs/.vitepress/dist.

2. Configurer le site (service de fichiers statiques) dans ServBay

   En mode production, le site VitePress est composé uniquement de fichiers statiques : il suffit donc d’utiliser ServBay pour les servir.

   Dans le panneau ServBay :

   • Nom : Par exemple Site VitePress Production.
   • Domaine : Par exemple, vitepress-prod.servbay.demo.
   • Type de site : Sélectionnez Statique.
   • Racine du site : Indiquez le chemin absolu du dossier généré précédemment : /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Enregistrez et appliquez : ServBay configurera le serveur web pour servir directement les fichiers statiques depuis ce répertoire.

3. Accéder au site de production

   Ouvrez https://vitepress-prod.servbay.demo dans votre navigateur pour visualiser le site VitePress final, servi avec domaine personnalisé et SSL automatique par ServBay.

Fonctionner en mode URLs propres (cleanUrls: true)

VitePress prend en charge l’option cleanUrls: true, supprimant l’extension .html des liens générés (par exemple /guide/ vs /guide/index.html, /about vs /about.html). Pour que le serveur web réponde correctement aux URLs propres, il faut quelques réglages.

ServBay utilise Caddy ou Nginx. Voici un exemple de configuration Caddy utilisant try_files pour chercher le fichier correspondant (avec extension .html ou index.html dans le dossier).

1. Activer cleanUrls dans VitePress

   Éditez le fichier docs/.vitepress/config.mts (ou config.ts), ajoutez/modifiez l’option :

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... autres options
     cleanUrls: true, // Active les URLs propres
     // ... autres options
   })

   Relancez npm run docs:build pour générer la version de production.

2. Configurer le site ServBay (Caddy personnalisé)

   Depuis l’onglet "Sites" de ServBay, trouvez le domaine de production (ex: vitepress-prod.servbay.demo) :

   • Cliquez sur "Éditer".
   • Cochez "Configuration personnalisée".
   • Dans la zone "Configuration Caddy", entrez la configuration suivante (remplacez les chemins et domaines selon votre cas) :

   # Remplacez par votre domaine réel, ex. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Active la compression Brotli (zstd) et Gzip
       encode zstd gzip
   
       # Importe la configuration de logs ServBay par défaut
       import set-log vitepress-cleanurl.servbay.demo
   
       # Gère automatiquement le certificat SSL interne
       tls internal
   
       # Coeur de la configuration: essaie différentes possibilités de fichier
       # 1. Fichier direct (ex: /about -> /about)
       # 2. index.html dans le dossier (ex: /guide/ -> /guide/index.html)
       # 3. Ajoute .html (ex: /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Définit la racine du site
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Sert les fichiers statiques
       file_server
   }

   Enregistrez et appliquez les changements.

3. Accéder au site en URLs propres

   Rendez-vous sur https://vitepress-cleanurl.servbay.demo : vos pages sont accessibles sans extension .html (ex: /about au lieu de /about.html ou /about/index.html).

Conclusion

Grâce à ce guide, vous savez maintenant comment créer, développer et déployer un site de documentation VitePress avec ServBay. ServBay simplifie l’administration de Node.js et la configuration locale des serveurs web, que ce soit en reverse proxy pour le développement ou en service de fichiers statiques pour la production. Il fournit automatiquement un domaine personnalisé et le SSL sans effort.

En combinant la puissance de ServBay et la flexibilité de VitePress, vous pouvez construire et maintenir des documentations techniques de haute qualité plus efficacement.