Tworzenie i uruchamianie projektu VitePress z użyciem ServBay

VitePress to nowoczesny generator stron statycznych napędzany przez Vue, zaprojektowany do szybkiego, estetycznego i łatwego w utrzymaniu tworzenia stron dokumentacyjnych. Bazuje na Vite, oferując doskonałe doświadczenia deweloperskie i wyjątkową wydajność kompilacji. Dla programistów poszukujących profesjonalnej dokumentacji dla projektów, bibliotek lub produktów, VitePress to znakomity wybór.

Podczas lokalnego rozwijania i testowania VitePress kluczowe jest posiadanie stabilnego i prostego w konfiguracji środowiska webowego. ServBay właśnie to zapewnia, integrując wiele wersji Node.js oraz wydajne serwery webowe (takie jak Caddy lub Nginx), umożliwiając bezproblemową obsługę Twoich projektów na VitePress.

W tym artykule dowiesz się, jak w pełni wykorzystać środowisko ServBay do stworzenia, skonfigurowania i uruchomienia projektu VitePress od podstaw, w tym ustawienia reverse proxy dla serwera deweloperskiego oraz serwowania plików statycznych w środowisku produkcyjnym.

Czym jest VitePress?

VitePress to statyczny generator stron (SSG) oparty na Vite, który wykorzystuje możliwości Vue 3 oraz szybkość Vite do budowy stron statycznych – idealnie nadaje się do tworzenia dokumentacji technicznej.

Kluczowe cechy i zalety VitePress

• Błyskawiczne środowisko deweloperskie: Dzięki HMR (hot module replacement) od Vite, zmiany w treści widoczne są niemal natychmiast w przeglądarce, znacznie zwiększając efektywność pracy.
• Napędzany przez Vue: Możesz swobodnie używać komponentów Vue bezpośrednio w plikach Markdown, co znacznie podnosi interaktywność dokumentacji.
• Prostota obsługi: Łatwy w konfiguracji, gotowy do użycia od razu po instalacji – skup się na tworzeniu treści.
• Wysoka wydajność: Wygenerowane pliki statyczne są lekkie i szybko się ładują; z wbudowanym routingiem po stronie klienta dają płynne doświadczenie single page application.
• Przyjazność SEO: Struktura HTML sprzyjająca wyszukiwarkom oraz wsparcie dla niestandardowych znaczników nagłówków.
• Ulepszony Markdown: Obsługa CommonMark, GitHub Flavored Markdown (GFM) oraz dodatkowej „cukru składniowego”.

Korzystając z VitePress, deweloperzy mogą bez większego wysiłku budować wysokiej jakości i wydajne strony dokumentacyjne.

Tworzenie i uruchamianie projektu VitePress z użyciem ServBay

ServBay umożliwia łatwą kontrolę wersji Node.js oraz konfigurację serwera webowego – zarówno na etapie developmentu, jak i produkcji, bez zbędnych komplikacji.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

1. Instalacja ServBay: Masz zainstalowany ServBay na swoim macOS. Jeśli jeszcze go nie masz, postępuj zgodnie z instrukcją instalacji ServBay.
2. Instalacja Node.js w ServBay: Upewnij się, że wymagane wersje Node.js są zainstalowane i aktywowane w ServBay (sprawdź w panelu ServBay na stronie „Pakiety”). Szczegóły: Korzystanie z Node.js.

Tworzenie projektu VitePress

1. Inicjalizacja folderu projektu

   Otwórz swoją aplikację terminala. Zaleca się utworzenie folderu projektu w domyślnym katalogu stron ServBay /Applications/ServBay/www, co ułatwi późniejszą konfigurację.

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

2. Instalacja VitePress i wstępna konfiguracja

   W katalogu projektu servbay-vitepress-app zainstaluj VitePress jako zależność developerską i uruchom inicjowanie projektu za pomocą npm lub yarn.

   npm add -D vitepress
   npx vitepress init

   Lub użyj Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Kreator zada Ci kilka podstawowych pytań o tytuł strony, opis itd. Przykład:

    ┌  Witaj w VitePress!
    │
    ◇  Gdzie zainicjować konfigurację VitePress?
    │  ./docs  # domyślny folder dokumentacji, potwierdź Enterem
    │
    ◇  Tytuł strony:
    │  ServBay VitePress Demo # wpisz tytuł, np. ServBay VitePress Demo
    │
    ◇  Opis strony:
    │  Strona VitePress na ServBay # wpisz opis strony
    │
    ◇  Motyw:
    │  Default Theme # wybierz Default Theme
    │
    ◇  Użyć TypeScriptu do plików konfiguracyjnych i motywów?
    │  Yes # zależnie od preferencji
    │
    ◇  Dodać skrypty VitePress do package.json?
    │  Yes # zalecane
    │
    └  Gotowe! Uruchom npm run docs:dev i zacznij pisać.

   Po zakończeniu powstanie podkatalog docs z plikami konfiguracyjnymi (.vitepress) i przykładowymi stronami (index.md, guide/index.md), a także zaktualizowany zostanie package.json o skrypty takie jak docs:dev i docs:build.

Edycja zawartości projektu VitePress

1. Edytowanie strony głównej

   Domyślna strona znajduje się w docs/index.md. Otwórz ją w wybranym edytorze tekstu i zmodyfikuj, np. tak:

   # Hello ServBay!
   
   Witamy w korzystaniu z ServBay do obsługi Twojej strony dokumentacyjnej VitePress.
   
   To jest lokalna strona demo, utworzona w VitePress i serwowana za pośrednictwem ServBay.

Rozpoczęcie pracy w trybie deweloperskim

Podczas developmentu korzystaj z wbudowanego serwera deweloperskiego VitePressa z hot-reloadem. Następnie skonfiguruj reverse proxy w ServBay, aby przeglądać stronę pod wybraną lokalną domeną z automatycznym SSL.

1. Uruchomienie serwera deweloperskiego VitePress

   Przejdź do katalogu projektu /Applications/ServBay/www/servbay-vitepress-app i uruchom:

   npm run docs:dev -- --port 8585

   Lub:

   yarn docs:dev --port 8585

   Serwer zacznie nasłuchiwać na wskazanym porcie (np. 8585). W terminalu pojawi się adres do lokalnego dostępu, np. http://localhost:8585.

2. Konfiguracja strony w ServBay (reverse proxy)

   Otwórz panel ServBay i przejdź na zakładkę „Strony”. Dodaj nową stronę:

   • Nazwa: np. VitePress - środowisko developerskie.
   • Domena: wybrana lokalna domena, np. vitepress-dev.servbay.demo.
   • Typ strony: wybierz Reverse proxy.
   • IP: 127.0.0.1 (localhost).
   • Port: np. 8585.

   Zapisz i zastosuj zmiany. ServBay automatycznie skonfiguruje serwer webowy (Caddy lub Nginx) do przekierowania ruchu z https://vitepress-dev.servbay.demo na http://127.0.0.1:8585.

3. Dostęp do środowiska developerskiego

   Teraz otwórz w przeglądarce https://vitepress-dev.servbay.demo. Powinieneś zobaczyć zawartość Twojej strony VitePress. Dzięki konfiguracji ServBay korzystasz z niestandardowej domeny i bezpiecznego certyfikatu SSL wystawionego przez ServBay User CA.

Budowanie wersji produkcyjnej

Po zakończeniu pracy nad dokumentacją VitePress czas na optymalną kompilację statycznej wersji do publikacji.

1. Budowanie wersji produkcyjnej

   W katalogu projektu /Applications/ServBay/www/servbay-vitepress-app uruchom:

   npm run docs:build

   albo:

   yarn docs:build

   Markdown i komponenty Vue zostaną skompilowane do zoptymalizowanych statycznych plików HTML, CSS i JS. Efekt znajdziesz w docs/.vitepress/dist.

2. Konfiguracja strony w ServBay (serwer plików statycznych)

   Wersja produkcyjna jest zestawem statycznych plików, które możesz udostępnić bezpośrednio przez ServBay.

   W panelu przejdź na „Strony” i dodaj konfigurację:

   • Nazwa: np. VitePress - środowisko produkcyjne.
   • Domena: np. vitepress-prod.servbay.demo.
   • Typ strony: wybierz Statyczna.
   • Katalog strony: wpisz pełną ścieżkę np. /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Zapisz i zastosuj zmiany. Serwer webowy został skonfigurowany, by serwować statyczne pliki z wybranego katalogu.

3. Dostęp do wersji produkcyjnej

   Teraz przeglądaj stronę produkcyjną pod adresem https://vitepress-prod.servbay.demo. Zobaczysz kompilację produkcyjną VitePress, również z obsługą niestandardowej domeny i automatycznym SSL.

Praca w trybie czystych adresów URL (cleanUrls: true)

VitePress obsługuje opcję cleanUrls: true, dzięki której linki pozbawione są rozszerzenia .html (np. /guide/ zamiast /guide/index.html czy /about zamiast /about.html). Aby serwer webowy poprawnie obsługiwał takie adresy, konieczna jest odpowiednia konfiguracja.

ServBay korzysta z Caddy lub Nginx. Przykład poniżej pokazuje konfigurację dla Caddy z dyrektywą try_files, umożliwiającą szukanie pliku z lub bez rozszerzenia .html oraz wersji folderowej.

1. Aktywuj cleanUrls w konfiguracji VitePress

   W pliku konfiguracyjnym docs/.vitepress/config.mts lub docs/.vitepress/config.ts w ustawieniach siteConfig dodaj lub zmodyfikuj opcję:

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

   Przebuduj projekt komendą npm run docs:build.

2. Kustomizacja konfiguracji Caddy w ServBay

   Otwórz panel ServBay, przejdź do edycji strony (np. vitepress-prod.servbay.demo).

   • Kliknij "Edytuj".
   • Zaznacz Konfiguracja niestandardowa.
   • W polu Konfiguracja Caddy wklej poniższą konfigurację, pamiętając o podmianie domeny i ścieżki:

   # Wpisz swoją domenę, np. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Włącz kompresję Brotli (zstd) i Gzip dla lepszych osiągów
       encode zstd gzip
   
       # Dołącz domyślną konfigurację logowania ServBay do debugowania
       import set-log vitepress-cleanurl.servbay.demo
   
       # Obsługa certyfikatów SSL przez ServBay (tryb internal)
       tls internal
   
       # Kluczowa dyrektywa: próba znalezienia żądanego pliku
       # 1. Sprawdza ścieżkę bez zmian (/about → /about)
       # 2. Sprawdza index.html w folderze (/guide/ → /guide/index.html)
       # 3. Sprawdza plik .html (/about → /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Katalog główny strony
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Serwowanie plików statycznych
       file_server
   }

   Zapisz i zastosuj zmiany.

3. Dostęp do strony w trybie czystych adresów

   Odwiedź skonfigurowaną domenę (np. https://vitepress-cleanurl.servbay.demo) – każda strona dostępna jest bez rozszerzenia .html (np. https://vitepress-cleanurl.servbay.demo/about).

Podsumowanie

Po lekturze tego artykułu potrafisz tworzyć, rozwijać i wdrażać dokumentację VitePress w środowisku ServBay. ServBay znacząco ułatwia zarządzanie środowiskiem Node.js i konfigurację lokalnego serwera webowego – zarówno dla reverse proxy na etapie developmentu, jak i do serwowania statycznych plików na produkcji, zapewniając od razu niestandardowe domeny oraz automatyczny certyfikat SSL.

W połączeniu z mocą ServBay i VitePress możesz szybciej i skuteczniej budować oraz utrzymywać wysokiej jakości dokumentację techniczną.