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:

1. Installeer ServBay: Zorg dat ServBay succesvol op je systeem is geïnstalleerd. Zo niet, volg dan de ServBay installatiegids.
2. 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

1. 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:

   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. VitePress installeren en configuratie initialiseren

   In de map servbay-vitepress-app installeer je VitePress als devDependency en start je de initiatie.

   npm add -D vitepress
   npx vitepress init

   Of via Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Tijdens 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.). De package.json wordt ook bijgewerkt met scripts zoals docs:dev en docs:build.

VitePress-content aanpassen

1. Homepage bewerken

   Het standaard beginbestand staat in docs/index.md. Open dit bestand met een teksteditor en vervang de inhoud bijvoorbeeld door:

   # 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.

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.

1. 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):

   npm run docs:dev -- --port 8585

   Of met Yarn:

   yarn docs:dev --port 8585

   De server draait nu op de gekozen poort, bijvoorbeeld http://localhost:8585.

2. 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 naar http://127.0.0.1:8585.

3. 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.

1. 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:

   npm run docs:build

   Of met Yarn:

   yarn docs:build

   Na het bouwen vind je de geoptimaliseerde statische bestanden in docs/.vitepress/dist.

2. 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

   Sla op en pas toe. Nu wordt je site rechtstreeks vanaf die map door de webserver geserveerd.

3. 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).

1. VitePress clean URLs inschakelen

   Pas je VitePress-configuratie aan (docs/.vitepress/config.mts of docs/.vitepress/config.ts) en voeg de optie cleanUrls toe:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... overige config
     cleanUrls: true, // Schakel clean URLs in
     // ... overige config
   })

   Run opnieuw npm run docs:build voor een nieuwe build.

2. 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

   # 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
   }

   Sla op en pas de wijzigingen toe.

3. Clean URL-site bezoeken

   Nu kun je je domein (bijv. https://vitepress-cleanurl.servbay.demo) zonder .html extensie gebruiken, bijvoorbeeld direct https://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.