VitePress-Projekte mit ServBay erstellen und betreiben

VitePress ist ein moderner Static Site Generator (SSG), der von Vue unterstützt wird und speziell für die Entwicklung schneller, ansprechender und leicht wartbarer Dokumentationswebsites konzipiert ist. Er basiert auf Vite und bietet exzellente Entwicklungserfahrung sowie hohe Performance beim Build. Für Entwickler, die professionelle Dokumentationen zu Projekten, Bibliotheken oder Produkten bereitstellen möchten, ist VitePress eine ausgezeichnete Wahl.

Für die lokale Entwicklung und das Testen von VitePress ist eine stabile und einfach konfigurierbare lokale Webentwicklungsumgebung unverzichtbar. ServBay wurde genau dafür entwickelt: Es bietet integrierte Node.js-Versionen und leistungsstarke Webserver (wie Caddy oder Nginx), die Ihr VitePress-Projekt unkompliziert ausliefern können.

In dieser Anleitung erfahren Sie, wie Sie mit der integrierten Umgebung von ServBay ein VitePress-Projekt von Grund auf neu erstellen, konfigurieren und betreiben − inklusive Einrichtung eines Reverse Proxys für den Entwicklungsserver sowie eines Static File Services für die Produktion.

Was ist VitePress?

VitePress ist ein auf Vite basierender Static Site Generator. Er nutzt die Leistungsfähigkeit von Vue 3 und die Geschwindigkeit von Vite, um statische Websites zu erstellen und eignet sich besonders zur Erstellung von technischen Dokumentationen.

Die wichtigsten Funktionen und Vorteile von VitePress

• Blitzschnelles Developer-Erlebnis: Dank Vites Hot Module Replacement (HMR) erscheinen Änderungen umgehend im Browser – für maximale Effizienz beim Schreiben.
• Vue-powered: Sie können Vue-Komponenten direkt in Markdown-Dateien verwenden und so Dokumentationen interaktiver und flexibler gestalten.
• Einfach und komfortabel: Minimaler Konfigurationsaufwand, sofort einsatzbereit – Fokus liegt auf dem Inhalt.
• Hochperformant: Die generierten statischen Dateien sind schlank und laden schnell; mit integriertem Client-side Routing erzielen Sie eine Single-Page-App-ähnliche User-Experience.
• SEO-optimiert: Die HTML-Struktur ist ideal für Suchmaschinen und unterstützt individuelle Header-Tags.
• Markdown-Enhancements: Unterstützung für CommonMark und GitHub Flavored Markdown (GFM) – plus zusätzliche Syntax-Erweiterungen.

Mit VitePress erstellen Sie mühelos leistungsfähige und hochwertige Dokumentationswebsites.

Mit ServBay ein VitePress-Projekt erstellen und betreiben

ServBay bietet eine bequeme Möglichkeit, Node.js-Versionen zu verwalten und Webserver für Ihr VitePress-Projekt zu konfigurieren − sei es im Entwicklungsmodus als Reverse Proxy oder als Static File Service für die Produktion.

Voraussetzungen

Bevor Sie starten, stellen Sie bitte Folgendes sicher:

1. ServBay installiert: ServBay muss erfolgreich auf Ihrem System installiert sein. Falls nicht, folgen Sie der ServBay Installationsanleitung.
2. Node.js-Paket installiert: In ServBay muss die gewünschte Node.js-Version installiert und aktiviert sein. Dies steuern Sie über die ServBay-Oberfläche auf der "Pakete"-Seite. Anleitung: Node.js verwenden.

VitePress-Projekt initialisieren

1. Projektverzeichnis anlegen

   Öffnen Sie Ihr Terminal. Es empfiehlt sich, das Projekt im Standard-Webroot-Verzeichnis von ServBay zu erstellen; das erleichtert die spätere Konfiguration.

   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 installieren und konfigurieren

   Wechseln Sie ins Projektverzeichnis servbay-vitepress-app und installieren Sie VitePress als Dev-Dependency. Führen Sie anschließend das Initialisierungskommando aus.

   npm add -D vitepress
   npx vitepress init

   Mit Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Der Initialisierungsprozess leitet Sie Schritt für Schritt durch die Basiskonfiguration − etwa Seitentitel, Beschreibung usw. Geben Sie die gewünschten Angaben ein:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Standard-Dokumentationsordner, einfach mit Enter bestätigen
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Geben Sie z.B. ServBay VitePress Demo als Titel ein
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Geben Sie die Seitenbeschreibung ein
    │
    ◇  Theme:
    │  Default Theme # Standardtheme auswählen
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Nach Präferenz: TypeScript-Konfiguration wählen
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # VitePress-Skripte zu package.json hinzufügen (empfohlen)
    │
    └  Done! Now run npm run docs:dev and start writing.

   Nun haben Sie ein Unterverzeichnis docs mit Konfigurationsdateien (.vitepress) und Beispieldateien (index.md, guide/index.md etc.). In package.json wurden die neuen Skripte docs:dev und docs:build ergänzt.

Inhalt des VitePress-Projekts anpassen

1. Startseite bearbeiten

   Die VitePress-Startseite liegt in docs/index.md. Öffnen Sie diese Datei mit einem Editor und passen Sie sie beispielsweise wie folgt an:

   # Hallo ServBay!
   
   Willkommen zu Ihrer VitePress-Dokumentationswebsite, betrieben mit ServBay.
   
   Dies ist eine lokale Demo-Seite, erstellt mit VitePress und ausgeliefert über ServBay.

Entwicklungsmodus aktivieren

Für die Entwicklung nutzen Sie meist den eingebauten VitePress-Dev-Server mit Hot Reload. Mit ServBay können Sie diesen über ein lokales Custom-Domain via Reverse Proxy und mit SSL-Verschlüsselung ausliefern.

1. VitePress-Entwicklungsserver starten

   Gehen Sie ins Projektverzeichnis (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Starten Sie den Dev-Server mit Portangabe (z.B. 8585).

   npm run docs:dev -- --port 8585

   Oder mit Yarn:

   yarn docs:dev --port 8585

   Der Server läuft nun auf dem angegebenen Port im lokalen Netz, meist unter http://localhost:8585.

2. ServBay-Webseite als Reverse Proxy einrichten

   Öffnen Sie die ServBay-Oberfläche und erstellen Sie eine neue Web-Konfiguration:

   • Name: Sinnvoller Name, z.B. VitePress Entwicklungsumgebung.
   • Domain: Local Domain, empfohlen mit dem Präfix .servbay.demo, z.B. vitepress-dev.servbay.demo.
   • Webseiten-Typ: Reverse Proxy auswählen.
   • IP: 127.0.0.1
   • Port: wie oben gewählt, z.B. 8585.

   Speichern Sie die Änderungen. ServBay konfiguriert nun automatisch den Webserver (Caddy/Nginx), sodass Anfragen an https://vitepress-dev.servbay.demo an http://127.0.0.1:8585 weitergeleitet werden.

3. Dev-Seite aufrufen

   Sie können Ihre Seite nun direkt via https://vitepress-dev.servbay.demo im Browser aufrufen. Dank ServBay nutzen Sie nicht nur Ihr Custom-Domain, sondern genießen auch automatische SSL-Verschlüsselung mit dem ServBay User CA-Zertifikat.

Produktionsbuild erstellen

Nach Abschluss der Dokumentationsentwicklung erzeugen Sie ein optimiertes, statisches Build Ihrer Site.

1. Produktionsbuild erstellen

   Navigieren Sie ins Projektverzeichnis (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Starten Sie den Build:

   npm run docs:build

   Oder mit Yarn:

   yarn docs:build

   Das Ergebnis ist eine Sammlung optimierter statischer HTML-, CSS- und JS-Dateien im Ordner docs/.vitepress/dist.

2. ServBay-Webseite als Static File Server aufsetzen

   Für die Produktion können Sie die Statische-Dateiserver-Funktion von ServBay nutzen.

   Öffnen Sie ServBay und fügen Sie eine neue Webseite hinzu:

   • Name: z.B. VitePress Produktionsumgebung.
   • Domain: Local Domain nach Wahl, z.B. vitepress-prod.servbay.demo.
   • Webseiten-Typ: Statisch.
   • Webseiten-Root: Absoluter Pfad zum Dist-Ordner:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Speichern und anwenden. ServBay liefert die statische Website nun direkt aus dem gewählten Verzeichnis.

3. Produktionsseite besuchen

   Besuchen Sie jetzt Ihr gewünschtes Domain, z.B. https://vitepress-prod.servbay.demo im Browser. Sie sehen die Produktivversion Ihrer VitePress-Website − inklusive Custom-Domain und automatisch eingerichtetem SSL.

Betrieb im Clean URL Modus (cleanUrls: true)

VitePress unterstützt das Setting cleanUrls: true. Das bedeutet, Page-URLs erscheinen ohne .html-Suffix (etwa /guide/ statt /guide/index.html oder /about statt /about.html). Damit der Webserver solche Anfragen korrekt auflöst, ist eine kleine Extra-Konfiguration nötig.

ServBay verwendet Caddy oder Nginx. Für Caddy finden Sie hier ein Beispiel, das per try_files-Direktive die richtigen Files sucht:

1. cleanUrls in VitePress aktivieren

   Bearbeiten Sie Ihre VitePress-Konfigurationsdatei (docs/.vitepress/config.mts oder docs/.vitepress/config.ts), und ergänzen Sie im siteConfig:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... weitere Einstellungen
     cleanUrls: true, // Clean URLs aktivieren
     // ... weitere Einstellungen
   })

   Bauen Sie das Produktions-Build erneut mit npm run docs:build.

2. ServBay-Webseite mit benutzerdefinierter Caddy-Konfiguration

   In ServBay, navigieren Sie zur Domain Ihrer Produktionsseite (z.B. vitepress-prod.servbay.demo):

   • Klicken Sie auf Bearbeiten,
   • wählen Sie „Benutzerdefinierte Konfiguration“,
   • und fügen Sie im Caddy-Config-Feld folgenden Inhalt ein − passen Sie Domain und Root entsprechend Ihrem Setup an:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Ersetzen Sie durch Ihre echte Domain, z.B. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Brotli (zstd) und Gzip-Kompression aktivieren für schnellere Ladezeiten
       encode zstd gzip
   
       # Standard-Logging von ServBay zur besseren Fehlerdiagnose
       import set-log vitepress-cleanurl.servbay.demo
   
       # Automatisches SSL mit ServBay internem Zertifikat
       tls internal
   
       # Wichtiger Teil: try_files sucht Dateien
       # 1. Versuche direkten Pfad (z.B. /about → /about)
       # 2. Versuche index.html im angeforderten Ordner (z.B. /guide/ → /guide/index.html)
       # 3. Versuche Pfad plus .html (z.B. /about → /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Root-Verzeichnis setzen
       # 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
   
       # Aktivieren Sie den Static File Server
       file_server
   }

   Änderungen speichern und anwenden.

3. Clean URL-Seite aufrufen

   Ihre Seite ist jetzt unter z.B. https://vitepress-cleanurl.servbay.demo erreichbar. Für Seiten im Clean-URL-Modus genügt nun die URL ohne .html − etwa für „about.html“ einfach https://vitepress-cleanurl.servbay.demo/about aufrufen.

Fazit

Mit dieser Anleitung wissen Sie, wie Sie in der ServBay-Umgebung eine VitePress-Dokumentationsseite entwickeln, betreiben und produktiv bereitstellen. ServBay vereinfacht die Node.js-Versionierung und Webserver-Konfiguration erheblich − egal, ob Sie im Dev-Modus mit Reverse Proxy oder produktiv mit Static File Server arbeiten. Domains und SSL-Zertifikate sind sofort und automatisch verfügbar.

Die Kombination aus ServBay und VitePress ermöglicht es Ihnen, technische Dokumentationen schnell, effizient und sicher zu erstellen und zu pflegen.