Créer et exécuter un projet VitePress avec ServBay

VitePress est un générateur de site statique moderne basé sur Vue, conçu pour créer des sites de documentation rapides, esthétiques et faciles à maintenir. S'appuyant sur Vite, il offre une expérience de développement optimale et des performances de build exceptionnelles. Pour les développeurs souhaitant documenter un projet, une bibliothèque ou un produit de façon professionnelle, VitePress constitue une solution idéale.

Pour le développement et le test local, disposer d’un environnement web stable et facilement configurable est primordial. ServBay répond précisément à ce besoin : il intègre plusieurs versions de Node.js ainsi que des serveurs web performants (comme Caddy ou Nginx), permettant ainsi de servir facilement votre projet VitePress.

Ce guide vous accompagne dans la création, la configuration et l'exécution d’un site VitePress avec ServBay, depuis l’initiation du projet jusqu’à la gestion du proxy inversé en mode développement et du service de fichiers statiques en production.

Qu'est-ce que VitePress ?

VitePress est un générateur de site statique (SSG) reposant sur Vite, combinant la puissance de Vue 3 et la rapidité de Vite pour produire des sites statiques, particulièrement adaptés à la documentation technique.

Principales fonctionnalités et avantages de VitePress

• Expérience de développement ultra-rapide : Grâce au Hot Module Replacement (HMR) de Vite, chaque modification s'affiche instantanément dans le navigateur, améliorant considérablement la productivité.
• Propulsé par Vue : Possibilité d’intégrer directement des composants Vue dans les fichiers Markdown, pour des documentations interactives et dynamiques.
• Simplicité d’utilisation : Configuration minimale et prêt-à-l’emploi, focalisée sur la création de contenu.
• Performances élevées : Les fichiers générés sont optimisés, légers et se chargent rapidement, tout en offrant la fluidité d’une application monopage grâce au routage client intégré.
• Optimisation SEO : La structure HTML produite facilite l’indexation par les moteurs de recherche et permet la personnalisation des balises head.
• Markdown enrichi : Prise en charge complète de CommonMark et GitHub Flavored Markdown (GFM), avec des ajouts syntaxiques exclusifs.

Avec VitePress, il est facile de créer des sites de documentation d’excellente qualité et hautement performants.

Créer et exécuter un projet VitePress avec ServBay

ServBay vous permet de gérer aisément les versions de Node.js et de configurer le serveur web pour votre projet VitePress, en mode développement comme en production.

Prérequis

Avant de commencer, assurez-vous d’avoir :

1. Installé ServBay : ServBay doit être opérationnel sur votre système. Si ce n’est pas déjà fait, suivez le guide d’installation de ServBay.
2. Ajouté le package Node.js : Vérifiez dans ServBay que la version souhaitée de Node.js est installée et activée via le panneau « Packages ». Consultez la section Utilisation de Node.js.

Initialiser un projet VitePress

1. Créer le dossier projet

   Lancez votre terminal. Il est conseillé de placer le dossier du projet dans le répertoire racine web par défaut de ServBay pour simplifier la configuration du site.

   macOS :

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

   Windows :

   cd C:\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 dépendance de développement avec npm ou yarn, puis lancez la commande d'initialisation.

   npm add -D vitepress
   npx vitepress init

   Ou avec Yarn :

   yarn add -D vitepress
   yarn vitepress init

   La commande d’init vous guidera pour renseigner des paramètres de base, comme le titre du site et sa description. Saisissez les informations selon les indications :

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Dossier par défaut, validez par 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, laissez par défaut
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Utiliser TypeScript pour la config, au choix
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Ajouter les scripts à package.json, recommandé
    │
    └  Done! Now run npm run docs:dev and start writing.

   Après l'initialisation, VitePress crée un dossier docs contenant les fichiers de configuration (.vitepress) et des pages exemples (index.md, guide/index.md, etc.), et modifie le package.json pour intégrer les scripts docs:dev et docs:build.

Modifier le contenu du projet VitePress

1. Éditer la page d’accueil

   Le fichier d’accueil de VitePress se trouve dans docs/index.md. Vous pouvez modifier le contenu à l’aide de l’éditeur de texte de votre choix, par exemple :

   # Bonjour ServBay !
   
   Bienvenue, lancez votre site documentaire VitePress avec ServBay.
   
   Ceci est une démonstration locale utilisant VitePress, servie via ServBay.

Passer en mode développement

Pour la phase de développement, le serveur intégré de VitePress propose le rechargement à chaud pour la prévisualisation immédiate. ServBay permet d’accéder à ce serveur via un domaine personnalisé et un certificat SSL.

1. Démarrer le serveur de développement VitePress

   Dans le terminal, assurez-vous d’être dans le dossier racine du projet (macOS : /Applications/ServBay/www/servbay-vitepress-app, Windows : C:\ServBay\www\servbay-vitepress-app). Lancez :

   npm run docs:dev -- --port 8585

   Ou avec Yarn :

   yarn docs:dev --port 8585

   Le serveur de développement écoutera le port spécifié (par exemple, 8585). L’adresse locale sera généralement http://localhost:8585.

2. Configurer le site ServBay (proxy inversé)

   Ouvrez le panneau ServBay et rendez-vous dans la section « Sites ». Ajoutez une nouvelle configuration :

   • Nom : Choisissez un nom parlant, comme Site de développement VitePress.
   • Domaine : Indiquez le nom de domaine local souhaité. Pour éviter tout conflit, utilisez de préférence le suffixe .servbay.demo, par exemple vitepress-dev.servbay.demo.
   • Type de site : Sélectionnez Proxy inversé.
   • IP : Saisissez 127.0.0.1 (localhost).
   • Port : Entrez le port défini à l’étape précédente, par exemple 8585.

   Validez et appliquez la configuration. ServBay configure automatiquement le serveur web (Caddy ou Nginx) pour relayer les requêtes https://vitepress-dev.servbay.demo vers http://127.0.0.1:8585.

3. Accéder au site de développement

   Ouvrez votre navigateur à l’adresse https://vitepress-dev.servbay.demo. Le contenu fourni par le serveur VitePress s’affichera, accessible via le domaine personnalisé et sécurisé grâce au certificat SSL généré par ServBay User CA.

Générer la version de production

Une fois la documentation prête, il convient de produire une version statique optimisée.

1. Construire la version de production

   Dans le terminal, dans le dossier racine du projet (macOS : /Applications/ServBay/www/servbay-vitepress-app, Windows : C:\ServBay\www\servbay-vitepress-app), lancez la commande :

   npm run docs:build

   Ou avec Yarn :

   yarn docs:build

   Cette étape compile tous vos fichiers Markdown et composants Vue en pages HTML, CSS et JavaScript optimisées. Les fichiers générés se trouvent dans docs/.vitepress/dist.

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

   Le site VitePress produit n’est qu’un ensemble de fichiers statiques : ServBay peut les servir directement.

   Ouvrez le panneau ServBay, section « Sites ». Ajoutez une nouvelle configuration :

   • Nom : Par exemple, Site VitePress Production.
   • Domaine : Le nom local pour la production, comme vitepress-prod.servbay.demo.
   • Type de site : Choisissez Statique.
   • Racine du site : Indiquez le chemin absolu vers les fichiers statiques générés :
     • macOS : /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows : C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Finalisez et appliquez la configuration. ServBay sert alors les fichiers statiques depuis le dossier transmis.

3. Accéder au site de production

   Accédez à https://vitepress-prod.servbay.demo pour tester le site VitePress final via le domaine configuré, bénéficiant aussi d’un certificat SSL automatique.

Utiliser le mode URL propre (cleanUrls: true)

VitePress propose l’option cleanUrls: true, supprimant l’extension .html des liens générés (par exemple /guide/ au lieu de /guide/index.html, ou /about pour /about.html). Pour que le serveur web gère correctement ces requêtes, une configuration dédiée est requise.

ServBay utilise Caddy ou Nginx comme serveur web. Voici un exemple avec Caddy, utilisant la directive try_files qui teste diverses variantes de fichiers.

1. Activer cleanUrls dans la configuration VitePress

   Modifiez le fichier de configuration VitePress (docs/.vitepress/config.mts ou docs/.vitepress/config.ts) afin d’ajouter ou ajuster la propriété cleanUrls :

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

   Puis relancez le build avec npm run docs:build.

2. Configurer ServBay (Caddy personnalisé)

   Dans ServBay (section « Sites »), repérez la configuration du site de production (e.g. vitepress-prod.servbay.demo).

   • Cliquez sur « Éditer ».
   • Cochez Configuration personnalisée.
   • Dans la zone de texte dédiée à la config Caddy, collez le code ci-dessous en adaptant le domaine et le chemin d’accès :
     • macOS : /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows : C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Remplacez par votre réel domaine (ex : vitepress-cleanurl.servbay.demo)
   vitepress-cleanurl.servbay.demo {
       # Activez la compression Brotli (zstd) et Gzip pour accélérer le chargement
       encode zstd gzip
   
       # Importez la configuration de logs ServBay pour faciliter le debug
       import set-log vitepress-cleanurl.servbay.demo
   
       # Gérez l’installation du certificat SSL interne ServBay
       tls internal
   
       # Directive clé : recherche du fichier cible
       # 1. Cherche le chemin directement (/about -> /about)
       # 2. Tente /index.html dans le dossier (/guide/ -> /guide/index.html)
       # 3. Essaie avec .html ajouté (/about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Définissez le dossier racine du site
       # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
       # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Activez le service de fichiers statiques
       file_server
   }

   Sauvegardez et appliquez la modification.

3. Accéder au site en mode « clean URLs »

   Rendez-vous sur votre domaine dédié (ex : https://vitepress-cleanurl.servbay.demo). Les pages dotées de cleanUrls seront accessibles sans extension .html : par exemple, pour la page about.html, utilisez simplement https://vitepress-cleanurl.servbay.demo/about.

Synthèse

Grâce à ce guide, vous savez désormais comment élaborer, développer et déployer un site documentaire VitePress avec ServBay. La gestion des environnements Node.js et la configuration du serveur web sont grandement simplifiées, que ce soit en mode proxy inversé pour le développement ou en mode service statique pour la production, avec la prise en charge automatique des noms de domaine personnalisés et des certificats SSL.

En combinant ServBay et VitePress, vous pouvez concevoir et maintenir efficacement des documentations techniques de haute qualité.