Erstellung und Betrieb eines VitePress-Projekts mit ServBay

VitePress ist ein moderner, von Vue unterstützter, statischer Website-Generator. Er ist speziell für den Aufbau schneller, schöner und einfach zu wartender Dokumentationswebsites konzipiert. VitePress basiert auf Vite und bietet eine erstklassige Entwicklererfahrung sowie hohe Build-Performance. Für Entwickler, die professionelle Dokumentationen für Projekte, Bibliotheken oder Produkte benötigen, ist VitePress eine ausgezeichnete Wahl.

Beim lokalen Entwickeln und Testen von VitePress ist eine stabile, einfach konfigurierbare lokale Webentwicklungsumgebung unerlässlich. Genau dafür wurde ServBay entwickelt: Es integriert verschiedene Node.js-Versionen und leistungsstarke Webserver wie Caddy oder Nginx, sodass Sie Ihre VitePress-Projekte mühelos bereitstellen können.

In diesem Beitrag erfahren Sie, wie Sie mit Hilfe von ServBays integrierter Umgebung von Grund auf ein VitePress-Projekt erstellen, konfigurieren und betreiben – einschließlich Reverse Proxy für den Entwicklungsserver und statischer Dateifreigabe für den Produktivbetrieb.

Was ist VitePress?

VitePress ist ein auf Vite basierender statischer Website-Generator (SSG). Er nutzt die Leistungsfähigkeit von Vue 3 und die Geschwindigkeit von Vite zur Erstellung statischer Websites – ideal vor allem für technische Dokumentationen.

Hauptmerkmale und Vorteile von VitePress

• Blitzschnelle Entwicklung: Dank Hot Module Replacement (HMR) von Vite sehen Sie Ihre Änderungen quasi in Echtzeit im Browser – extrem effizient beim Entwickeln.
• Vue-basiert: Sie können Vue-Komponenten direkt in Markdown-Dateien nutzen, was Ihre Dokumentation interaktiv und ausdrucksstark macht.
• Einfacher Einstieg: Die Konfiguration ist minimal, direkt einsatzbereit und auf Inhaltsproduktion fokussiert.
• Hohe Performance: Die generierten Dateien sind schlank und laden schnell; zusammen mit integrierter Clientseitennavigation entsteht ein reibungsloses Single Page-Erlebnis.
• SEO-optimiert: Der erzeugte HTML-Code ist suchmaschinenfreundlich, und benutzerdefinierte Head-Tags werden unterstützt.
• Markdown-Features: Unterstützung für CommonMark und Github Flavored Markdown (GFM) sowie zusätzliche Syntaxerweiterungen.

Mit VitePress können Entwickler hochwertige und performante Dokumentationsseiten mit Leichtigkeit aufbauen.

VitePress-Projekt mit ServBay erstellen und betreiben

ServBay bietet eine komfortable Möglichkeit, Node.js-Versionen zu verwalten und Webserver so zu konfigurieren, dass Ihr VitePress-Projekt entweder im Entwicklungsmodus oder produktiv als statische Website betrieben werden kann.

Voraussetzungen

Bitte stellen Sie vorab sicher, dass Folgendes erfüllt ist:

1. ServBay installiert: ServBay ist erfolgreich auf Ihrem macOS installiert. Falls nicht, folgen Sie bitte der Installationsanleitung von ServBay.
2. Node.js-Paket installiert: In ServBay sollte Ihre gewünschte Node.js-Version installiert und aktiviert sein. Dies verwalten Sie über die "Pakete"-Seite im ServBay Control Panel. Siehe Node.js verwenden.

VitePress-Projekt anlegen

1. Projektverzeichnis initialisieren

   Öffnen Sie Ihr Terminal. Es empfiehlt sich, das Projekt im Standard-Webverzeichnis von ServBay /Applications/ServBay/www anzulegen, um die spätere Konfiguration zu erleichtern.

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

2. VitePress installieren und Grundkonfiguration durchführen

   Wechseln Sie in das Verzeichnis servbay-vitepress-app und installieren Sie VitePress als Entwicklungsabhängigkeit, dann initialisieren Sie das Projekt.

   npm add -D vitepress
   npx vitepress init

   Alternativ mit Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Das Initialisierungskommando leitet Sie durch einige Basiseinstellungen wie Seitentitel oder Beschreibung. Geben Sie die geforderten Informationen 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 Ihren Seitentitel ein, z. B. ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Geben Sie eine Beschreibung der Seite ein
    │
    ◇  Theme:
    │  Default Theme # Thema auswählen; Standard-Thema genügt
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Wunschgemäß auswählen, ob TypeScript genutzt werden soll
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Ob Scripts zu package.json hinzugefügt werden; "Yes" wird empfohlen
    │
    └  Done! Now run npm run docs:dev and start writing.

   Nach Abschluss findet sich ein Unterverzeichnis docs im Projekt mit VitePress-Konfiguration (.vitepress) und Beispielseiten (index.md, guide/index.md etc.). Auch die package.json wird um Befehle wie docs:dev und docs:build erweitert.

Inhalte des VitePress-Projekts bearbeiten

1. Startseite bearbeiten

   Die Standard-Startseite von VitePress liegt unter docs/index.md. Öffnen Sie diese mit einem beliebigen Editor und passen Sie den Inhalt an, etwa wie folgt:

   # Hello ServBay!
   
   Willkommen bei der Ausführung Ihrer VitePress-Dokumentationswebsite mittels ServBay.
   
   Dies ist eine lokale Demo-Seite mit VitePress, bereitgestellt durch ServBay.

Entwicklungsmodus aktivieren

Beim Entwickeln nutzen Sie gewöhnlich den eingebaute VitePress-Server mit Hot Reload. Mit ServBays Reverse Proxy können Sie den Server über eine lokale Domain – inklusive SSL – erreichen.

1. VitePress-Entwicklungsserver starten

   Wechseln Sie ins Projektverzeichnis (/Applications/ServBay/www/servbay-vitepress-app) und starten Sie den Server mit einer Port-Angabe, etwa 8585:

   npm run docs:dev -- --port 8585

   Alternativ mit Yarn:

   yarn docs:dev --port 8585

   Der Server läuft nun lokal unter dem angegebenen Port, z.B. http://localhost:8585.

2. ServBay-Website für Reverse Proxy konfigurieren

   Öffnen Sie das ServBay-Control Panel, navigieren Sie zum Bereich "Websites" und fügen Sie eine neue Konfiguration hinzu:

   • Name: Geben Sie z.B. VitePress Entwicklungsseite ein.
   • Domain: Verwenden Sie eine gewünschte lokale Domain, empfohlen wird das .servbay.demo-Suffix, beispielhaft vitepress-dev.servbay.demo.
   • Website-Typ: Wählen Sie Reverse Proxy.
   • IP: Tragen Sie 127.0.0.1 (localhost) ein.
   • Port: Der aus Schritt 1 genutzte Port, z.B. 8585.

   Nach dem Speichern übernimmt ServBay die Konfiguration automatisch. Fortan werden Aufrufe auf https://vitepress-dev.servbay.demo an den lokalen VitePress-Server unter http://127.0.0.1:8585 weitergeleitet.

3. Entwicklungsseite aufrufen

   Sie können jetzt https://vitepress-dev.servbay.demo im Browser öffnen und die von VitePress bereitgestellte Seite sehen. Dank ServBay erhalten Sie automatisch ein SSL-Zertifikat der ServBay User CA für verschlüsselte HTTPS-Verbindungen mit Ihrer lokalen Domain.

Produktionsversion bauen

Wenn Ihre Dokumentation fertig ist und veröffentlicht werden soll, erzeugen Sie einen optimierten statischen Build.

1. Produktivversion bauen

   Wechseln Sie ins Projektverzeichnis /Applications/ServBay/www/servbay-vitepress-app und führen Sie:

   npm run docs:build

   Oder mit Yarn:

   yarn docs:build

   Der Build kompiliert Ihre Markdown-Dateien, Vue-Komponenten usw. in optimiertes HTML, CSS und JavaScript. Die fertigen statischen Dateien finden sich im Ordner docs/.vitepress/dist.

2. ServBay-Konfiguration für statische Datei-Auslieferung

   Für die statische Version nutzt ServBay den Modus "Statisch". Gehen Sie im Control Panel unter "Websites" wie folgt vor:

   • Name: Geben Sie z.B. VitePress Produktionsseite ein.
   • Domain: Wir empfehlen z.B. vitepress-prod.servbay.demo.
   • Website-Typ: Wählen Sie Statisch.
   • Root-Verzeichnis: Tragen Sie das Build-Verzeichnis ein: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Speichern und übernehmen Sie die Änderungen. ServBay stellt nun Ihre Website direkt aus diesem Verzeichnis bereit.

3. Produktionswebsite aufrufen

   Rufen Sie https://vitepress-prod.servbay.demo in Ihrem Browser auf. Dort sehen Sie Ihre optimierte statische Website. Auch hier sorgt ServBay für Domain und SSL-Verschlüsselung.

Betrieb mit Clean URLs (cleanUrls: true)

Mit cleanUrls: true generiert VitePress Links ohne .html-Endung (z. B. /guide/ statt /guide/index.html oder /about statt /about.html). Die Webserver-Konfiguration muss für solche URLs angepasst werden.

ServBay nutzt Caddy oder Nginx als Webserver. Nachfolgend ein Beispiel für die nötige Caddy-Konfiguration, welche mit try_files verschiedene Dateivarianten für eine angefragte URL prüft.

1. cleanUrls in der VitePress-Konfiguration aktivieren

   Öffnen Sie die VitePress-Konfigurationsdatei (docs/.vitepress/config.mts oder docs/.vitepress/config.ts) und ergänzen Sie:

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

   Führen Sie anschließend erneut npm run docs:build aus.

2. ServBay-Website mit individueller Caddy-Konfiguration einrichten

   Im ServBay-Control Panel unter "Websites" finden Sie die Produktions-Domain (z. B. vitepress-prod.servbay.demo):

   • Klicken Sie auf "Bearbeiten".
   • Aktivieren Sie die Benutzerdefinierte Konfiguration.
   • Fügen Sie im Caddy-Konfigurationsfeld Folgendes ein (achten Sie darauf, servbay-vitepress-test.prod durch Ihren Domainnamen und den Pfad auf Ihr tatsächliches Build-Verzeichnis anzupassen):

   # Ersetzen Sie diese Domain, z. B. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Brotli (zstd) und Gzip-Komprimierung für schnellere Ladezeiten
       encode zstd gzip
   
       # ServBay-Standard-Logging einbinden (hilfreich zum Debuggen)
       import set-log vitepress-cleanurl.servbay.demo
   
       # ServBay-interne SSL-Zertifikatsverwaltung aktivieren
       tls internal
   
       # Zentrale Regel: Versuche, die Datei wie folgt zu finden
       # 1. Direkter Pfad (z. B. /about -> /about)
       # 2. index.html im Verzeichnis (z. B. /guide/ -> /guide/index.html)
       # 3. .html-Datei zum Pfad (z. B. /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Verzeichnis für statische Dateien angeben
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Statische Dateiauslieferung aktivieren
       file_server
   }

   Änderungen speichern und übernehmen.

3. Website mit Clean URLs aufrufen

   Rufen Sie Ihre Seite (z. B. https://vitepress-cleanurl.servbay.demo) im Browser auf. Dank der Clean-URL-Konfiguration sind nun alle Seiten – etwa /about statt /about.html – wie erwartet erreichbar.

Fazit

Mit dieser Anleitung haben Sie gelernt, wie Sie unter ServBay eine VitePress-Dokumentationswebsite erstellen, entwickeln und produktiv bereitstellen. ServBay erleichtert nicht nur das Node.js-Management, sondern auch die lokale Webserver-Konfiguration – ganz gleich ob im Reverse Proxy für den Entwicklungsmodus oder als statischer Dateiserver für die Produktion. Domains und SSL-Zertifikate werden dabei automatisch verwaltet.

Mit der leistungsstarken Kombination aus ServBay und VitePress können Sie Ihre Technische Dokumentation effizient und auf professionellem Niveau erstellen und betreiben.