Een VitePress-project maken en uitvoeren met ServBay

VitePress is een moderne statische site generator, aangedreven door Vue, ontworpen voor snelle, aantrekkelijke en eenvoudig te onderhouden documentatiesites. Gebouwd op Vite biedt het een uitstekende ontwikkelervaring en bouwprestaties. Voor ontwikkelaars die professionele documentatie willen aanbieden bij hun project, library of product, is VitePress een uitstekende keuze.

Tijdens lokale ontwikkeling en testen met VitePress is een stabiele en eenvoudig te configureren lokale webontwikkelomgeving essentieel. ServBay voorziet hierin door meerdere versies van de Node.js-omgeving te integreren met krachtige webservers (zoals Caddy of Nginx), waarmee je eenvoudig je VitePress-project kunt runnen.

In dit artikel begeleiden we je bij het opzetten, configureren en uitvoeren van een VitePress-project in de geïntegreerde ServBay-omgeving, inclusief het instellen van een reverse proxy voor de ontwikkelserver en het serveren van statische bestanden voor productie.

Wat is VitePress?

VitePress is een statische site generator (SSG) op basis van Vite. Het benut de kracht van Vue 3 en de snelheid van Vite om razendsnelle statische sites te genereren – ideaal voor technische documentatie.

Belangrijkste kenmerken en voordelen van VitePress

• Supersnelle ontwikkelervaring: Dankzij Vite's hot module replacement (HMR) zie je wijzigingen vrijwel direct terug in de browser, wat snel itereren mogelijk maakt.
• Aangedreven door Vue: Gebruik rechtstreeks Vue-componenten in Markdown-bestanden voor interactieve en expressieve documentatie.
• Eenvoudig in gebruik: Direct uit de doos te gebruiken met minimale configuratie; focus volledig op je content.
• Hoge prestaties: Genereert lichte, snel ladende statische bestanden en biedt een soepele single-page-app-ervaring dankzij ingebouwde client routering.
• SEO-vriendelijk: De gegenereerde HTML is geoptimaliseerd voor zoekmachines en ondersteunt custom head-tags.
• Uitgebreide Markdown-ondersteuning: Volledige ondersteuning voor CommonMark en GitHub Flavored Markdown (GFM), aangevuld met handige extra syntaxis.

Met VitePress bouw je eenvoudig hoogwaardige, performante documentatiesites.

Een VitePress-project maken en uitvoeren met ServBay

ServBay biedt een gemakkelijke manier om Node.js-versies te beheren en webservers te configureren voor je VitePress-project, zowel tijdens ontwikkeling als in productie.

Vereisten

Zorg ervoor dat je aan de volgende voorwaarden voldoet voordat je begint:

1. Installeer ServBay: Zorg dat ServBay succesvol is geïnstalleerd op je macOS-systeem. Volg eventueel de ServBay installatiegids.
2. Installeer Node.js-pakket: Controleer in ServBay of het benodigde Node.js-pakket geïnstalleerd en ingeschakeld is. Dit regel je via het "Pakketten"-scherm in het ServBay dashboard. Zie Node.js gebruiken.

Een VitePress-project aanmaken

1. Projectmap initialiseren

   Open eerst je terminal-applicatie. We raden aan je projectmap aan te maken in de standaard webroot van ServBay op /Applications/ServBay/www, zodat de site later eenvoudig geconfigureerd kan worden in ServBay.

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

2. Installeer VitePress en initialiseer de configuratie

   Installeer VitePress als dev dependency in de map servbay-vitepress-app en start het initialisatieproces met npm of yarn.

   npm add -D vitepress
   npx vitepress init

   Of met Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Het initialisatieproces begeleidt je door enkele basisinstellingen, zoals de website-titel en -omschrijving. Volg de aanwijzingen:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Standaard map voor documentatie, druk gewoon op Enter
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Voer je website titel in, bijv. ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Typ hier een omschrijving van de site
    │
    ◇  Theme:
    │  Default Theme # Kies een thema – standaard is prima
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # TypeScript-configuratie: kies naar voorkeur
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Scripts toevoegen aan package.json – aanbevolen om Yes te kiezen
    │
    └  Done! Now run npm run docs:dev and start writing.

   Na de initialisatie wordt een docs-submap aangemaakt met standaardconfiguratie (.vitepress) en voorbeeldpagina’s (index.md, guide/index.md enz.). Ook wordt je package.json automatisch geüpdatet met scripts als docs:dev en docs:build.

VitePress-website aanpassen

1. Homepagina bewerken

   De default-homepagina vind je in docs/index.md. Open dit bestand in je favoriete teksteditor en pas de inhoud aan, bijvoorbeeld:

   # Hello ServBay!
   
   Welkom bij het draaien van jouw VitePress documentatiesite op ServBay.
   
   Dit is een lokale demo website, aangemaakt met VitePress en gehost via ServBay.

Starten in ontwikkelmodus

Tijdens het ontwikkelen van je VitePress-site gebruik je doorgaans de ingebouwde dev-server, waarmee je in realtime wijzigingen kunt bekijken dankzij hot reload. Met de reverse proxy-functionaliteit van ServBay kun je daarnaast eenvoudig via een eigen domeinnaam én met SSL op de dev-server werken.

1. Dev-server van VitePress starten

   Zorg dat je je in de projectroot bevindt: /Applications/ServBay/www/servbay-vitepress-app. Start de dev-server met bijvoorbeeld poort 8585:

   npm run docs:dev -- --port 8585

   Of met Yarn:

   yarn docs:dev --port 8585

   De dev-server draait nu lokaal en luistert op het opgegeven poortnummer (zoals 8585). De terminal toont het lokale adres, meestal http://localhost:8585.

2. Instellen van je site in ServBay (reverse proxy)

   Open het ServBay-dashboard en ga naar de pagina "Websites". Voeg een nieuwe website toe:

   • Naam: Geef een herkenbare naam, bijv. VitePress-ontwikkelsite.
   • Domein: Kies een lokale ontwikkeldomeinnaam, bij voorkeur eindigend op .servbay.demo, zoals vitepress-dev.servbay.demo.
   • Type website: Kies Reverse Proxy.
   • IP: Vul 127.0.0.1 in (localhost).
   • Poort: Gebruik hetzelfde poortnummer uit stap 1, zoals 8585.

   Sla de configuratie op en pas de veranderingen toe. ServBay configureert nu automatisch de webserver (bijvoorbeeld Caddy of Nginx) zodanig dat verkeer naar https://vitepress-dev.servbay.demo wordt doorgezet naar http://127.0.0.1:8585.

3. Je ontwikkelsite bezoeken

   Open in de browser het domein https://vitepress-dev.servbay.demo. Je ziet nu je VitePress-site via de dev-server. Dankzij de ServBay-instellingen werk je direct via een eigen domeinnaam én met SSL-certificaat van ServBay User CA voor een beveiligde HTTPS-verbinding.

Productieversie bouwen

Als je documentatie klaar is om online te zetten, kun je een geoptimaliseerde statische site bouwen.

1. Productiebouw uitvoeren

   Ga in de terminal naar /Applications/ServBay/www/servbay-vitepress-app en bouw de productieversie:

   npm run docs:build

   Of met Yarn:

   yarn docs:build

   Je Markdown, Vue-componenten e.d. worden gebundeld tot geoptimaliseerde statische HTML-, CSS- en JS-bestanden. Het resultaat komt terecht in de map docs/.vitepress/dist binnen je projectdirectory.

2. Website instellen in ServBay (statische bestanden)

   Omdat een productiever VitePress-site uit statische bestanden bestaat, kun je ServBay’s "Statische bestanden"-functie gebruiken.

   Open het ServBay-dashboard en ga naar "Websites". Voeg een nieuwe site toe:

   • Naam: Geef een naam, bijv. VitePress-productiesite.
   • Domein: Voer je lokale productiedomeinnaam in, bijv. vitepress-prod.servbay.demo.
   • Type website: Kies Statisch.
   • Webroot: Geef het absolute pad op naar de dist-map van de build: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Sla de configuratie op en pas deze toe. De webserver wordt nu ingesteld om direct statische bestanden te serveren vanuit de gekozen map.

3. Je productiesite bezoeken

   Bezoek in de browser het domein https://vitepress-prod.servbay.demo. Je ziet nu de productieversie van je VitePress-site, compleet met aangepaste domeinnaam en automatisch SSL via ServBay.

Clean URLs inschakelen (cleanUrls: true)

VitePress ondersteunt de instelling cleanUrls: true, waarmee URL's geen .html-extensie bevatten (zoals /guide/ in plaats van /guide/index.html, of /about in plaats van /about.html). Hiervoor moet de webserver correct worden geconfigureerd.

ServBay gebruikt Caddy of Nginx als webserver. Hieronder een voorbeeldconfiguratie voor Caddy met de try_files directive om bestanden slim op te zoeken (zoals .html-extensie of index.html binnen een map).

1. Activeer cleanUrls in de VitePress-configuratie

   Bewerk je VitePress-configuratiebestand (docs/.vitepress/config.mts of docs/.vitepress/config.ts) en voeg/haal de optie cleanUrls toe binnen siteConfig:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... overige configuratie
     cleanUrls: true, // Clean URLs activeren
     // ... overige configuratie
   })

   Draai vervolgens opnieuw npm run docs:build voor een nieuwe productie-build.

2. ServBay-website configureren (aangepaste Caddy-configuratie)

   Ga in het ServBay-dashboard naar "Websites" en zoek de productiesite van VitePress (bijvoorbeeld vitepress-prod.servbay.demo).

   • Klik op de bewerk-knop.
   • Vink Aangepaste configuratie aan.
   • Vul onder Caddy-configuratie de volgende code in. Let op: vervang servbay-vitepress-test.prod door je daadwerkelijke domeinnaam en het locatiepad door de juiste webroot.

   # Vervang met jouw eigen domeinnaam, bijv. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Brotli (zstd) en Gzip compressie activeren voor snellere laadtijden
       encode zstd gzip
   
       # ServBay standaard logging importeren voor debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Interne SSL-certificaten van ServBay activeren
       tls internal
   
       # Belangrijk: bestanden zoeken in deze volgorde:
       # 1. Direct bijbehorend pad (bv. /about -> /about)
       # 2. index.html in map (bv. /guide/ -> /guide/index.html)
       # 3. .html-bestand (bv. /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Webroot instellen
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Statische bestanden serveren
       file_server
   }

   Sla de wijzigingen op en pas ze toe.

3. De clean URL-site bezoeken

   Ga naar het ingestelde domein (zoals https://vitepress-cleanurl.servbay.demo). Voor pagina's met cleanUrls ingesteld, kun je nu URLs zonder .html-extensie gebruiken – bijvoorbeeld de pagina about.html bezoek je rechtstreeks via https://vitepress-cleanurl.servbay.demo/about.

Samenvatting

Met deze handleiding heb je geleerd hoe je in de ServBay-omgeving een VitePress documentatie-site maakt, ontwikkelt en online zet. ServBay vereenvoudigt het beheer van Node.js-versies en de lokale webserverconfiguratie. Of je nu een reverse proxy gebruikt voor ontwikkeling of statische bestanden in productie serveert: met ServBay is het snel en eenvoudig, inclusief automatisch beheer van domeinnamen en SSL-certificaten.

Door ServBay en VitePress te combineren beschik je over een krachtige, efficiënte en professionele workflow voor het ontwikkelen en onderhouden van hoogwaardige technische documentatie.