Tworzenie i uruchamianie projektu VitePress z ServBay

VitePress to nowoczesny generator statycznych stron internetowych wspierany przez Vue, zaprojektowany z myślą o szybkiej, atrakcyjnej i łatwej w utrzymaniu dokumentacji projektów. Zbudowany w oparciu o Vite oferuje doskonałe doświadczenie developera i wysoką wydajność kompilacji. Dla programistów potrzebujących profesjonalnych stron dokumentacyjnych dla projektów, bibliotek lub produktów, VitePress jest doskonałym wyborem.

Podczas lokalnej pracy z VitePress kluczowe jest stabilne i łatwe w konfiguracji lokalne środowisko webowe. ServBay zapewnia właśnie takie rozwiązanie, integrując wiele wersji Node.js oraz wydajne serwery webowe (jak Caddy lub Nginx), które w prosty sposób obsłużą Twój projekt VitePress.

W tym poradniku dowiesz się, jak wykorzystać zintegrowane środowisko ServBay do stworzenia, skonfigurowania i uruchomienia projektu VitePress od podstaw, włącznie z ustawieniem proxy zwrotnego dla developmentu oraz serwisu plików statycznych dla wersji produkcyjnej.

Czym jest VitePress?

VitePress to generator statycznych stron (SSG), zbudowany na Vite i wykorzystujący możliwości Vue 3 oraz superszybką kompilację Vite do tworzenia statycznych serwisów, szczególnie sprawdzających się przy dokumentacji technicznej.

Główne zalety i cechy VitePress

• Szybkie iteracje developerskie: Dzięki Hot Module Replacement (HMR) Vite, zmiany wprowadzone w kodzie są natychmiast widoczne w przeglądarce, co znacznie przyspiesza rozwój.
• Napędzany przez Vue: Możliwość używania komponentów Vue bezpośrednio w plikach Markdown, wzbogaca interaktywność i możliwości prezentacji dokumentacji.
• Prosta obsługa: Minimalna konfiguracja, działanie "out of the box", skupienie na tworzeniu treści.
• Wysoka wydajność: Dzięki generowaniu lekkich plików statycznych, strony ładują się błyskawicznie, a wbudowany klient zapewnia płynne wrażenia jak w SPA.
• Przyjazny SEO: Wygenerowana struktura HTML ułatwia indeksację przez wyszukiwarki i pozwala na pełną kontrolę nad tagami meta.
• Rozszerzony Markdown: Obsługuje pełny CommonMark oraz GitHub Flavored Markdown (GFM), oferując dodatkowe "cukierki" syntaktyczne.

Dzięki VitePress, twórcy mogą z łatwością budować wysoce wydajne i profesjonalne strony dokumentacyjne.

Tworzenie i uruchamianie projektu VitePress z ServBay

ServBay udostępnia wygodną obsługę wersji Node.js oraz prostą konfigurację serwera webowego do obsługi projektu VitePress – zarówno w trybie developerskim, jak i produkcyjnym.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że wykonałeś następujące czynności:

1. Zainstaluj ServBay: ServBay powinien być poprawnie zainstalowany w Twoim systemie. Jeżeli nie, skorzystaj z instrukcji instalacji ServBay.
2. Zainstaluj pakiet Node.js: W ServBay upewnij się, że wybrany pakiet Node.js jest zainstalowany oraz aktywowany. Możesz zarządzać wersjami z poziomu panelu ServBay na stronie "Pakiety". Sprawdź dokumentację: Jak używać Node.js.

Tworzenie projektu VitePress

1. Inicjalizacja katalogu projektu

   Otwórz wybrany terminal. Zaleca się utworzenie katalogu projektu w domyślnym katalogu root ServBay, co ułatwi późniejszą konfigurację serwisu.

   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. Instalacja VitePress i inicjalizacja konfiguracji

   W katalogu servbay-vitepress-app zainstaluj VitePress jako zależność developerską i uruchom komendę inicjalizacji.

   npm add -D vitepress
   npx vitepress init

   lub za pomocą Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Podczas inicjalizacji zostaniesz poproszony o kilka podstawowych danych (np. tytuł strony, opis itd.). Wprowadź odpowiednie informacje zgodnie z instrukcjami:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Domyślny katalog dokumentacji, wystarczy zatwierdzić Enterem
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Podaj tytuł strony, np. ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Podaj opis strony
    │
    ◇  Theme:
    │  Default Theme # Wybierz domyślny motyw
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Wybierz wg preferencji, o ile chcesz korzystać z TypeScript
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Zalecane dodanie skryptów do package.json
    │
    └  Done! Now run npm run docs:dev and start writing.

   Po zakończeniu VitePress utworzy podkatalog docs oraz domyślne pliki konfiguracyjne (.vitepress) i przykładowe strony (index.md, guide/index.md itd.). Zaktualizowany zostanie też package.json (m.in. dodane skrypty docs:dev, docs:build).

Edycja zawartości projektu VitePress

1. Edycja strony głównej

   Domyślny plik główny znajduje się w docs/index.md. Otwórz go w ulubionym edytorze i zmodyfikuj np. tak:

   # Hello ServBay!
   
   Witamy w ServBay! Tutaj możesz uruchomić własną stronę dokumentacji VitePress.
   
   Jest to lokalna strona demo stworzona za pomocą VitePress i udostępniona przez ServBay.

Tryb developerski

Przy tworzeniu stron VitePress najwygodniejszy jest wbudowany serwer developerski z funkcją hot reload do podglądu zmian na żywo. ServBay pozwala utworzyć proxy zwrotny przez niestandardową domenę oraz zapewnia automatyczny SSL.

1. Uruchom serwer developerski VitePress

   Przejdź do katalogu głównego projektu (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Uruchom serwer dev na wybranym porcie, np. 8585.

   npm run docs:dev -- --port 8585

   lub poprzez Yarn:

   yarn docs:dev --port 8585

   Serwer będzie nasłuchiwał lokalnie na wskazanym porcie (np. 8585), a adres zostanie wyświetlony w terminalu (np. http://localhost:8585).

2. Konfiguracja strony w ServBay (proxy zwrotne)

   Wejdź do panelu ServBay, sekcja "Strony". Kliknij "Dodaj nową konfigurację strony".

   • Nazwa: np. VitePress — środowisko developerskie
   • Domena: wybierz lokalną domenę (zalecany sufiks .servbay.demo, np. vitepress-dev.servbay.demo)
   • Typ strony: Proxy zwrotny
   • IP: 127.0.0.1 (localhost)
   • Port: podaj port wybrany w kroku 1, np. 8585

   Po zapisaniu ServBay automatycznie skonfiguruje serwer (Caddy lub Nginx), by przekierowywać żądania pod https://vitepress-dev.servbay.demo na http://127.0.0.1:8585.

3. Podgląd strony developerskiej

   Uruchom przeglądarkę i wpisz skonfigurowaną domenę: https://vitepress-dev.servbay.demo. Wyświetli się podgląd wersji dev VitePress. Dzięki ServBay uzyskujesz nie tylko własną domenę, ale także automatyczny certyfikat SSL od ServBay User CA, czyli bezpieczne HTTPS.

Budowanie wersji produkcyjnej

Po zakończeniu prac i przygotowaniu finalnej dokumentacji VitePress warto wygenerować zoptymalizowaną wersję statyczną.

1. Budowa wersji produkcyjnej

   Będąc w folderze głównym projektu (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), uruchom komendę budowania:

   npm run docs:build

   lub Yarn:

   yarn docs:build

   Markdown oraz komponenty Vue zostaną skompilowane do serii zoptymalizowanych plików HTML, CSS, JS w folderze docs/.vitepress/dist.

2. Konfiguracja strony produkcyjnej w ServBay (obsługa plików statycznych)

   Żeby obsłużyć gotowe pliki statyczne, użyj funkcji "obsługi statycznej" ServBay.

   W panelu wybierz "Strony" > "Dodaj nową konfigurację":

   • Nazwa: np. VitePress — wersja produkcyjna
   • Domena: np. vitepress-prod.servbay.demo
   • Typ strony: Statyczna
   • Katalog www: absolutna ścieżka do folderu z plikami:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Zapisz i zastosuj zmiany, ServBay skonfiguruje serwer webowy do obsługi plików bezpośrednio z katalogu produkcyjnego.

3. Podgląd strony produkcyjnej

   Wpisz w przeglądarce skonfigurowaną domenę: https://vitepress-prod.servbay.demo. Wyświetli się finalna wersja strony. Co istotne, ServBay obsługuje niestandardowe domeny i własny SSL automatycznie.

Obsługa czystych URL (cleanUrls: true)

VitePress umożliwia konfigurację cleanUrls: true, czyli generowanie linków stron bez rozszerzenia .html (np. /guide/ zamiast /guide/index.html, /about zamiast /about.html). Żeby serwer www poprawnie obsłużył takie adresy, potrzebna jest dodatkowa konfiguracja.

ServBay korzysta z Caddy lub Nginx. Przykład dla Caddy — użycie directivy try_files, która sprawdza m.in. istnienie plików z .html lub index.html.

1. Włącz cleanUrls w konfiguracji VitePress

   Edytuj plik konfiguracyjny VitePress (docs/.vitepress/config.mts lub docs/.vitepress/config.ts), dodając/zmieniając opcję cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... inne ustawienia
     cleanUrls: true, // Włącz czyste URL
     // ... inne ustawienia
   })

   Przebuduj projekt: npm run docs:build

2. Konfiguracja niestandardowa w ServBay (Caddy)

   W panelu ServBay przejdź do strony produkcyjnej (np. vitepress-prod.servbay.demo):

   • Edytuj konfigurację strony
   • Zaznacz opcję Niestandardowa konfiguracja
   • W oknie konfiguracji Caddy wklej poniższą konfigurację, pamiętając o podmianie domeny i ścieżki root na Twoje wartości:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Podmień na swoją domenę, np. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Enable Brotli (zstd) and Gzip compression for faster loading
       encode zstd gzip
   
       # Import default ServBay logging settings for easier debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Handle internal ServBay SSL certificates automatically
       tls internal
   
       # Core: try to match files for clean URLs
       # 1. Try direct file match (e.g. /about -> /about)
       # 2. Try index.html in directory (e.g. /guide/ -> /guide/index.html)
       # 3. Try file.html (e.g. /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Set document root
       # 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
   
       # Enable static file server
       file_server
   }

   Zapisz i zastosuj zmiany w ServBay.

3. Podgląd strony w trybie czystych URL

   Od teraz pod Twoją domeną (np. https://vitepress-cleanurl.servbay.demo) można otwierać strony bez rozszerzeń .html, np. strona about.html dostępna będzie pod adresem https://vitepress-cleanurl.servbay.demo/about.

Podsumowanie

Korzystając z tego poradnika, nauczyłeś się jak stworzyć, rozwijać i wdrażać stronę dokumentacji VitePress w środowisku ServBay. ServBay znacząco upraszcza zarządzanie wersjami Node.js i konfiguracją serwera webowego — zarówno dla proxy zwrotnego w trybie developerskim, jak i serwisu plików statycznych dla wersji produkcyjnej. Zyskujesz także natychmiastową obsługę niestandardowych domen i certyfikatów SSL.

Potężne połączenie ServBay i VitePress pozwala na szybkie i wygodne budowanie oraz utrzymanie wysokiej jakości dokumentacji technicznej.