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 :
- 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.
- 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
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 :
bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Windows :
cmdcd C:\ServBay\www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Installer 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.bashnpm add -D vitepress npx vitepress init
1
2Ou avec Yarn :
bashyarn add -D vitepress yarn vitepress init
1
2La 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 lepackage.json
pour intégrer les scriptsdocs:dev
etdocs:build
.
Modifier le contenu du projet VitePress
É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 :markdown# Bonjour ServBay ! Bienvenue, lancez votre site documentaire VitePress avec ServBay. Ceci est une démonstration locale utilisant VitePress, servie via ServBay.
1
2
3
4
5
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.
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 :bashnpm run docs:dev -- --port 8585
1Ou avec Yarn :
bashyarn docs:dev --port 8585
1Le serveur de développement écoutera le port spécifié (par exemple, 8585). L’adresse locale sera généralement
http://localhost:8585
.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 exemplevitepress-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
vershttp://127.0.0.1:8585
.- Nom : Choisissez un nom parlant, comme
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.
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 :bashnpm run docs:build
1Ou avec Yarn :
bashyarn docs:build
1Cette é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
.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
- macOS :
Finalisez et appliquez la configuration. ServBay sert alors les fichiers statiques depuis le dossier transmis.
- Nom : Par exemple,
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.
Activer
cleanUrls
dans la configuration VitePressModifiez le fichier de configuration VitePress (
docs/.vitepress/config.mts
oudocs/.vitepress/config.ts
) afin d’ajouter ou ajuster la propriétécleanUrls
:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... autres paramètres cleanUrls: true, // Active les URL propres // ... autres paramètres })
1
2
3
4
5
6
7
8Puis relancez le build avec
npm run docs:build
.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
- macOS :
bash# 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25Sauvegardez et appliquez la modification.
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 decleanUrls
seront accessibles sans extension.html
: par exemple, pour la pageabout.html
, utilisez simplementhttps://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é.