Een VitePress-project aanmaken en uitvoeren met ServBay
VitePress is een moderne generator voor statische websites, aangedreven door Vue, en speciaal ontworpen om snelle, aantrekkelijke en eenvoudig te onderhouden documentatiesites te bouwen. Het is gebaseerd op Vite, wat garant staat voor een uitstekende ontwikkelervaring en build-prestaties. Voor ontwikkelaars die professionele documentatie willen maken voor hun project, library of product is VitePress een uitstekende keuze.
Voor lokale ontwikkeling en testen met VitePress is een stabiele en eenvoudig te configureren webontwikkelomgeving onmisbaar. ServBay biedt precies dit: het integreert meerdere versies van Node.js en krachtige webservers (zoals Caddy of Nginx), zodat je eenvoudig je VitePress-project lokaal kunt bedienen.
In dit artikel leer je hoe je het geïntegreerde ServBay-platform gebruikt om vanaf nul een VitePress-project op te zetten, te configureren en te runnen, inclusief het instellen van een reverse proxy voor je ontwikkelserver en het serveren van statische bestanden voor productie.
Wat is VitePress?
VitePress is een static site generator (SSG) die is gebouwd bovenop Vite en gebruikmaakt van de krachtige features van Vue 3 en de razendsnelle bundeling van Vite om statische websites te creëren. Vooral voor technische documentatie blinkt VitePress uit.
Belangrijkste kenmerken en voordelen van VitePress
- Razendsnelle ontwikkelervaring: Dankzij Vite's hot module replacement (HMR) zie je updates vrijwel direct in je browser na het opslaan, wat de ontwikkelsnelheid enorm verhoogt.
- Aangedreven door Vue: Je kunt direct Vue-componenten gebruiken in Markdown-bestanden, wat je documentatie interactiever en expressiever maakt.
- Gebruiksgemak: Simpele configuratie, direct uit de doos te gebruiken, volledig gericht op het creëren van content.
- Hoge performance: De gegenereerde statische bestanden zijn klein en laden snel. De ingebouwde client-side router zorgt voor een soepele single-page ervaring.
- SEO-vriendelijk: HTML wordt zo gegenereerd dat zoekmachines deze goed kunnen indexeren, plus ondersteuning voor eigen head-tags.
- Verbeterde Markdown: Volledige ondersteuning voor CommonMark en GitHub Flavored Markdown (GFM), plus extra syntactic sugar.
Met VitePress kun je zonder gedoe hoogwaardige, snelle en goed vindbare documentatiesites bouwen.
Een VitePress-project maken en uitvoeren met ServBay
ServBay maakt het beheren van Node.js-versies en het configureren van webservers voor je VitePress-project eenvoudig, zowel voor lokale ontwikkeling als productiehosting van statische bestanden.
Voorwaarden
Zorg voor het volgende voordat je begint:
- Installeer ServBay: Zorg dat ServBay succesvol op je systeem is geïnstalleerd. Zo niet, volg dan de ServBay installatiegids.
- Installeer Node.js-pakket: In ServBay moet je de gewenste versie van het Node.js-pakket installeren en activeren. Beheer dit via het "Packages"-scherm van de ServBay-console. Zie Node.js gebruiken.
VitePress-project aanmaken
Projectdirectory initialiseren
Open je terminal. Het is aan te raden om je projectmap aan te maken in ServBay's standaard root-directory, zodat het later eenvoudig via ServBay kan worden bediend.
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
3VitePress installeren en configuratie initialiseren
In de map
servbay-vitepress-app
installeer je VitePress als devDependency en start je de initiatie.bashnpm add -D vitepress npx vitepress init
1
2Of via Yarn:
bashyarn add -D vitepress yarn vitepress init
1
2Tijdens de initiatie wordt je gevraagd om basisgegevens in te voeren, zoals titel en beschrijving van je site. Vul deze naar wens in:
┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # Standaard documentatie-map, druk op Enter om te bevestigen │ ◇ Site title: │ ServBay VitePress Demo # Vul de titel van je site in, bijvoorbeeld ServBay VitePress Demo │ ◇ Site description: │ A VitePress site running on ServBay # Vul een beschrijving in │ ◇ Theme: │ Default Theme # Kies het thema, standaard is prima │ ◇ Use TypeScript for config and theme files? │ Yes # Kies naar voorkeur TypeScript │ ◇ Add VitePress npm scripts to package.json? │ Yes # Voeg scripts toe aan package.json, aanbevolen │ └ Done! Now run npm run docs:dev and start writing.
Na initiatie maakt VitePress een
docs
submap met daarin een standaard configuratiemap (.vitepress
) en voorbeeldpagina's (index.md
,guide/index.md
etc.). Depackage.json
wordt ook bijgewerkt met scripts zoalsdocs:dev
endocs:build
.
VitePress-content aanpassen
Homepage bewerken
Het standaard beginbestand staat in
docs/index.md
. Open dit bestand met een teksteditor en vervang de inhoud bijvoorbeeld door:markdown# Hello ServBay! Welkom bij ServBay, dé oplossing om je VitePress documentatiesite te hosten. Dit is een lokale demo-website gemaakt met VitePress en geserveerd via ServBay.
1
2
3
4
5
In de ontwikkelmodus gaan
Tijdens het ontwikkelen van je VitePress-site gebruik je vaak de ingebouwde dev-server met hot-reloading. Via ServBay kun je eenvoudig via een eigen domein en SSL je dev-server benaderen, door reverse proxy te gebruiken.
VitePress dev-server starten
Ga in de terminal naar je project-root (
macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app
). Run de dev-server op een zelfgekozen poort (bijvoorbeeld 8585):bashnpm run docs:dev -- --port 8585
1Of met Yarn:
bashyarn docs:dev --port 8585
1De server draait nu op de gekozen poort, bijvoorbeeld
http://localhost:8585
.ServBay site-configuratie (reverse proxy) instellen
Open de ServBay-console en ga naar "Websites". Voeg een nieuwe config toe:
- Naam: Geef een herkenbare naam, bijvoorbeeld
VitePress ontwikkelsite
. - Domein: Vul het lokale ontwikkeldomein in, bijvoorbeeld
vitepress-dev.servbay.demo
. - Type website: Kies
Reverse proxy
. - IP-adres: Vul in
127.0.0.1
. - Poort: Vul de eerder gebruikte poort in, bijvoorbeeld
8585
.
Sla op en pas toe. ServBay configureert de webserver (zoals Caddy of Nginx) zodat alle aanvragen naar
https://vitepress-dev.servbay.demo
worden doorgestuurd naarhttp://127.0.0.1:8585
.- Naam: Geef een herkenbare naam, bijvoorbeeld
De ontwikkelsite bezoeken
Nu kun je je domein
https://vitepress-dev.servbay.demo
in de browser bezoeken. Je ziet nu de output van de VitePress dev-server. Dankzij ServBay heb je direct een eigen domein én een automatisch SSL-certificaat uitgereikt door de ServBay User CA voor een veilige https-verbinding.
Productieversie bouwen
Is je documentatie klaar om te publiceren? Bouw dan een geoptimaliseerde statische versie.
Productie build uitvoeren
Ga in de terminal naar de project-root (macOS:
/Applications/ServBay/www/servbay-vitepress-app
, Windows:C:\ServBay\www\servbay-vitepress-app
). Bouw de productieversie:bashnpm run docs:build
1Of met Yarn:
bashyarn docs:build
1Na het bouwen vind je de geoptimaliseerde statische bestanden in
docs/.vitepress/dist
.ServBay-site instellen (statische bestanden)
Je productie-website bestaat uit statische bestanden en kan direct via ServBay worden geserveerd.
Open de ServBay-console, ga naar "Websites", en voeg een nieuwe site toe:
- Naam: Geef een duidelijke naam, bijv.
VitePress productie-site
. - Domein: Vul het domein voor de live-site in, bijv.
vitepress-prod.servbay.demo
. - Type website: Kies
Static
. - Root-directory: Voer het absolute pad in van je statische build:
- macOS:
/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
- Windows:
C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
- macOS:
Sla op en pas toe. Nu wordt je site rechtstreeks vanaf die map door de webserver geserveerd.
- Naam: Geef een duidelijke naam, bijv.
Productiesite bezoeken
Via je domein
https://vitepress-prod.servbay.demo
kun je nu de live-site bekijken. Ook hier zorgt ServBay voor je eigen domein en automatische SSL.
Gebruik van clean URL-modus (cleanUrls: true
)
VitePress ondersteunt cleanUrls: true
, waardoor je links krijgt zonder .html
-extensie (zoals /guide/
in plaats van /guide/index.html
). Hiervoor moet de webserver goed worden ingesteld.
ServBay gebruikt Caddy of Nginx als webserver. Hieronder een voorbeeld voor Caddy, die via try_files
probeert het juiste bestand te vinden (zoals .html
of index.html
in een directory).
VitePress clean URLs inschakelen
Pas je VitePress-configuratie aan (
docs/.vitepress/config.mts
ofdocs/.vitepress/config.ts
) en voeg de optiecleanUrls
toe:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... overige config cleanUrls: true, // Schakel clean URLs in // ... overige config })
1
2
3
4
5
6
7
8Run opnieuw
npm run docs:build
voor een nieuwe build.ServBay-site instellen met aangepaste Caddy-config
Ga in ServBay-console naar je productiesite (bijv.
vitepress-prod.servbay.demo
).- Klik op "Bewerken".
- Vink "Custom config" aan.
- Vul het onderstaande Caddy-configuratievoorbeeld in, pas domein en pad aan naar jouw situatie:
- macOS:
/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
- Windows:
C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
- macOS:
bash# Vervang met jouw domein, bv. vitepress-cleanurl.servbay.demo vitepress-cleanurl.servbay.demo { # Zet Brotli (zstd) en Gzip compressie aan voor snelle laadtijden encode zstd gzip # Voeg ServBay's standaard logging toe voor debugging import set-log vitepress-cleanurl.servbay.demo # Gebruik het interne SSL-certificaat van ServBay tls internal # Try_files logica: # 1. Probeer direct het pad te matchen (/about -> /about) # 2. Probeer index.html in de directory (/guide/ -> /guide/index.html) # 3. Probeer .html erbij (/about -> /about.html) try_files {path} {path}/index.html {path}.html # Root-directory instellen: # 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 # Activeer de static file server 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
25Sla op en pas de wijzigingen toe.
Clean URL-site bezoeken
Nu kun je je domein (bijv.
https://vitepress-cleanurl.servbay.demo
) zonder.html
extensie gebruiken, bijvoorbeeld directhttps://vitepress-cleanurl.servbay.demo/about
.
Samenvatting
Met deze handleiding kun je nu een VitePress documentatiesite ontwikkelen, bouwen en uitrollen in een ServBay-omgeving. ServBay maakt het beheer van Node.js-versies en de configuratie van je lokale webserver eenvoudig, voor zowel reverse proxy tijdens ontwikkeling als directe static hosting voor productie — inclusief snelle domeininstelling en automatische SSL-certificaten.
Dankzij ServBay en VitePress bouw en onderhoud je efficiënt hoogwaardige technische documentatie, klaar voor snelle lokale ontwikkeling en professionele presentatie.