Instalacja i konfiguracja Jigsaw w środowisku ServBay

Przegląd

Ten dokument ma na celu przeprowadzenie Cię przez proces instalacji oraz konfiguracji statycznego generatora stron Jigsaw w potężnym lokalnym środowisku ServBay. ServBay oferuje zintegrowane środowisko dla różnych technologii takich jak PHP, Node.js, co znacząco upraszcza uruchamianie projektów Jigsaw. Dzięki ServBay możesz łatwo skonfigurować lokalną domenę, HTTPS oraz wydajny serwer WWW dla swojego projektu Jigsaw, skupiając się wyłącznie na rozwijaniu treści strony.

Czym jest Jigsaw?

Jigsaw to statyczny generator stron oparty na komponentach Laravel, rozwijany przez firmę Tighten. Wykorzystuje on moc i elastyczność silnika szablonów Blade z Laravel oraz pliki Markdown do generowania czystych statycznych stron HTML. Jigsaw świetnie sprawdza się przy tworzeniu dokumentacji, blogów, landing page'y czy innych serwisów, które nie wymagają zaplecza bazy danych ani dynamicznej obsługi po stronie serwera. Najważniejsze zalety Jigsaw:

• Wykorzystanie znanych narzędzi: Jeśli znasz Laravel lub szablony Blade, pracę z Jigsaw rozpoczniesz błyskawicznie.
• Wydajność i bezpieczeństwo: Statyczne strony ładują się szybko i są bardzo bezpieczne, ponieważ nie jest wykonywany żaden kod po stronie serwera.
• Elastyczne szablony: Dzięki Blade tworzysz złożone układy i komponenty.
• Wsparcie Markdown: Tworzenie treści jest wygodne i szybkie.

Zastosowania

Jigsaw jest idealny do:

• Dokumentacji projektowych i API
• Blogów osobistych lub technicznych
• Stron promocyjnych firmy lub produktu
• Małych stron-wizytówek
• Stron wymagających wysokiej wydajności i bezpieczeństwa oraz o względnie statycznej treści

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

1. ServBay jest zainstalowany i uruchomiony: Musisz mieć zainstalowany i uruchomiony ServBay na macOS. ServBay zawiera już PHP, Composer oraz Node.js/npm — wymagane do pracy z Jigsaw.
2. Podstawowa znajomość terminala: Czeka Cię praca z linią poleceń.
3. Podstawowa wiedza o Composer i npm: Instalacja Jigsaw wykorzystuje Composer, a kompilacja zasobów frontendowych — npm.

Kroki instalacji i konfiguracji

W tej sekcji znajdziesz szczegółowy opis kolejnych etapów instalacji i konfiguracji projektu Jigsaw w środowisku ServBay.

Krok 1: Utworzenie katalogu projektu

Najpierw otwórz terminal i przejdź do zalecanego katalogu głównego stron ServBay: /Applications/ServBay/www, a następnie utwórz nowy katalog na swój projekt Jigsaw.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Nazwaliśmy katalog projektu servbay-jigsaw-demo — w nim będą przechowywane wszystkie pliki projektu.

Krok 2: Utworzenie projektu Jigsaw za pomocą Composer

ServBay posiada już zainstalowany i skonfigurowany Composer, co pozwala na jego użycie w dowolnym terminalu. Będąc w katalogu projektu (/Applications/ServBay/www/servbay-jigsaw-demo), uruchom poniższe polecenie:

composer create-project tightenco/jigsaw .

Polecenie to pobierze najnowszą wersję Jigsaw i wszystkie zależności PHP właśnie do bieżącego katalogu (.). Zwróć uwagę na kropkę na końcu — oznacza ona instalację bezpośrednio w aktualnym folderze.

Krok 3: Konfiguracja strony w ServBay

Aby przeglądać swoją stronę Jigsaw w przeglądarce, musisz skonfigurować projekt jako lokalną stronę w ServBay.

1. Otwórz ServBay UI: Kliknij ikonę aplikacji lub użyj ikonki w pasku menu, aby otworzyć panel kontrolny ServBay.
2. Przejdź do „Strony”: W lewej nawigacji wybierz zakładkę „Strony”.
3. Dodaj nową stronę: Na dole interfejsu kliknij „+” i wybierz „Dodaj stronę”.
4. Uzupełnij dane strony:
   • Nazwa (Name): Wpisz rozpoznawalną nazwę, np. ServBay Jigsaw Demo.
   • Domena (Domain): Podaj domenę, pod jaką chcesz mieć lokalny dostęp. Zalecamy końcówkę .servbay.demo (np. jigsaw-demo.servbay.demo), aby uniknąć konfliktów z prawdziwymi domenami; ServBay automatycznie przekieruje ruch z tej domeny na lokalny host.
   • Typ strony (Site Type): Wybierz PHP, ponieważ Jigsaw do budowy potrzebuje środowiska PHP.
   • Wersja PHP (PHP Version): Wskaż wybraną, najlepiej najnowszą stabilną wersję PHP dostępną w ServBay.
   • Katalog główny strony (Site Root): To kluczowa opcja. Po zbudowaniu Jigsaw domyślnie umieszcza pliki wyjściowe w katalogu build_local. Wskaż go jako katalog główny strony: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Zapisz i zastosuj: Po uzupełnieniu wszystkich pól kliknij „Zapisz”. ServBay poprosi Cię o potwierdzenie zmiany — wybierz „Potwierdź”. Konfiguracja serwera WWW (Caddy lub Nginx) oraz HTTPS zostaną wykonane automatycznie.

Krok 4: Instalacja zależności frontendowych

Projekty Jigsaw zazwyczaj korzystają z npm do zarządzania i kompilacji zasobów frontendowych (np. SASS, pliki JavaScript). Dzięki ServBay Node.js i npm masz od razu gotowe do użycia.

W katalogu projektu (/Applications/ServBay/www/servbay-jigsaw-demo) uruchom komendę:

npm install

Polecenie to odczyta plik package.json i pobierze wymagane moduły Node.js do katalogu node_modules.

Krok 5: Zbudowanie strony Jigsaw

Po zainstalowaniu wszystkich zależności uruchom polecenie budowy Jigsaw, które wygeneruje pliki statyczne strony:

./vendor/bin/jigsaw build

To polecenie:

1. Przetwarza pliki Markdown i szablony Blade z katalogu source.
2. Uruchamia zadania kompilacji zdefiniowane w webpack.mix.js, jeżeli korzystasz z Laravel Mix.
3. Umieszcza wygenerowane strony HTML, CSS, JS oraz inne pliki w katalogu build_local.

Krok 6: Dostęp do strony

W tym momencie gotowe pliki statyczne znajdują się w /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Ponieważ wybrałeś ten katalog jako główny folder strony w ServBay, możesz teraz sprawdzić działanie strony poprzez przeglądarkę.

Otwórz przeglądarkę i wpisz skonfigurowaną wcześniej domenę, np. https://jigsaw-demo.servbay.demo. ServBay automatycznie zadba o certyfikat HTTPS (z wykorzystaniem ServBay User CA) i zobaczysz domyślną stronę powitalną Jigsaw.

Personalizacja i rozwój

Po prawidłowym skonfigurowaniu środowiska możesz swobodnie modyfikować treść i wygląd swojej strony Jigsaw.

Edycja zawartości i szablonów

• Kod źródłowy strony znajduje się w katalogu source w głównym folderze projektu.
• Układy i komponenty HTML bazujące na Blade znajdziesz w source/_layouts oraz source/_partials.
• Treść stron przygotowujesz w plikach Markdown umieszczonych bezpośrednio w source lub w podkatalogach (np. source/index.md, source/about.md).
• Wpisy blogowe umieszcza się najczęściej w source/_posts, stosując format nazw: YYYY-MM-DD-slug.md.

Dodawanie nowej strony/wpisu

Aby dodać nową stronę lub post na bloga, utwórz nowy plik Markdown w odpowiednim katalogu, np. source/about.md:

---
title: "O nas"
description: "Dowiedz się więcej o ServBay Jigsaw Demo"
---

# O nas

To jest strona „O nas” utworzona w Jigsaw.

Tu możesz dodać informacje o firmie lub zespole — według uznania.

Personalizacja stylów i skryptów

Projekty Jigsaw korzystają zazwyczaj z Laravel Mix (plik webpack.mix.js) do kompilacji zasobów frontendowych:

• Pliki stylów (najczęściej SASS/SCSS) umieść w source/_assets/sass
• Pliki JavaScript — w source/_assets/js

W katalogu projektu możesz zbudować te zasoby używając skryptów npm:

• npm run dev: kompilacja zasobów na potrzeby środowiska deweloperskiego (z mapowaniem źródeł, bez minifikacji).
• npm run watch: kompilacja deweloperska i automatyczne nasłuchiwanie zmian — bardzo wygodne przy pracy nad projektem.
• npm run prod: kompilacja produkcyjna — pliki zostają zminifikowane i zoptymalizowane.

Gdy np. zmodyfikujesz source/_assets/sass/main.scss, uruchom npm run dev lub npm run watch by wygenerować zaktualizowany plik CSS.

Ponowna budowa strony

Ważne: Każdorazowa zmiana plików treści (Markdown) lub szablonów (Blade) w katalogu source wymaga ponownego zbudowania strony poleceniem:

./vendor/bin/jigsaw build

Jeżeli edytowałeś pliki frontendu (SASS, JS), skorzystaj z npm run dev lub npm run watch, by przekompilować te zasoby. W większości projektów Jigsaw polecenie build wywołuje również kompilację przez Mix, ale rozdzielenie tych procesów ułatwia debugowanie.

Ważne informacje

• Katalog wyjściowy: Domyślnie Jigsaw buduje pliki do build_local (dla środowiska developerskiego) i build_production (dla produkcji). Upewnij się, że w ServBay wybrałeś odpowiedni katalog jako root strony.
• Serwer WWW: ServBay obsługuje statyczne pliki poprzez Caddy lub Nginx — nie ma potrzeby uruchamiania jigsaw serve (serwer wbudowany w Jigsaw służy głównie do szybkiego podglądu i nie oferuje tylu funkcji).
• HTTPS: ServBay automatycznie skonfiguruje HTTPS dla domen .servbay.demo wydając certyfikaty przez ServBay User CA. By uniknąć ostrzeżeń przeglądarki, zalecamy dodać ServBay User CA do zaufanych certyfikatów systemowych.
• Czysta budowa: W przypadku problemów budowy warto uruchomić: ./vendor/bin/jigsaw build --clean.

Najczęściej zadawane pytania (FAQ)

P: Zmieniłem plik Markdown, ale nie widzę zmian w przeglądarce?

O: Po każdej zmianie treści lub szablonu uruchom ponownie polecenie ./vendor/bin/jigsaw build, aby zaktualizować stronę.

P: Edytowałem plik SCSS, ale style pozostają bez zmian?

O: Po każdej zmianie zasobów frontendowych uruchom npm run dev lub npm run watch w katalogu projektu, by ponownie je skompilować.

P: Po wejściu na lokalną domenę widzę błąd „nie znaleziono strony” lub brak plików?

O: Sprawdź:

1. Czy ServBay jest uruchomiony?
2. Czy konfiguracja strony w ServBay jest poprawna? Czy domena oraz root wskazują na /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Czy wykonałeś ./vendor/bin/jigsaw build i w katalogu build_local znajdują się wygenerowane pliki (np. index.html)?

P: Jak wdrożyć stronę Jigsaw na produkcję?

O: Jigsaw generuje czyste pliki statyczne. Typowa procedura:

1. Uruchom ./vendor/bin/jigsaw build production aby zbudować zoptymalizowaną wersję serwisu.
2. Wgraj cały katalog build_production do dowolnego dostawcy hostingu statycznych stron www (np. Netlify, Vercel, GitHub Pages, czy dowolną chmurę oferującą hosting statyczny).

Podsumowanie

ServBay umożliwia szybkie, wygodne i w pełni zintegrowane środowisko pracy z Jigsaw na systemie macOS. Dostarcza wszystkie niezbędne komponenty (PHP, Composer, Node.js, npm) oraz daje mocne wsparcie dla konfiguracji lokalnego serwera WWW. Postępując zgodnie z tym przewodnikiem, błyskawicznie uruchomisz projekt Jigsaw i wykorzystasz pełnię możliwości ServBay do optymalizacji własnego procesu lokalnej deweloperki.