Installation und Konfiguration von Jigsaw in der ServBay-Umgebung

Überblick

Dieses Dokument erläutert, wie Sie den Static Site Generator Jigsaw in der leistungsstarken lokalen Webentwicklungsumgebung von ServBay installieren und konfigurieren. ServBay bietet eine integrierte Umgebung für diverse Tech-Stacks wie PHP und Node.js und vereinfacht dadurch den Aufbau von Jigsaw-Projekten enorm. Dank ServBay können Sie mit wenigen Klicks lokale Domains, HTTPS und performante Webserver für Ihr Jigsaw-Projekt konfigurieren und sich voll auf die Entwicklung der Website-Inhalte konzentrieren.

Was ist Jigsaw?

Jigsaw ist ein statischer Website-Generator, der auf Laravel-Komponenten basiert und von Tighten entwickelt wird. Er nutzt die Leistungsfähigkeit und Flexibilität des Laravel Blade-Template-Engines und kombiniert diese mit Markdown-Dateien zur Erstellung reiner statischer HTML-Websites. Jigsaw eignet sich ideal für Dokumentationsseiten, Blogs, Landingpages oder beliebige Websites, die keine dynamische Server-Logik oder Backend-Datenbank benötigen. Die wichtigsten Vorteile von Jigsaw sind:

• Bekannte Werkzeuge nutzen: Wer bereits Laravel oder Blade kennt, wird sich in Jigsaw sofort heimisch fühlen.
• Performance und Sicherheit: Die generierten statischen Websites laden sehr schnell und sind besonders sicher, da kein Server-Code ausgeführt wird.
• Flexible Templates: Mit Blade-Templates lassen sich auch komplexe Layouts und Komponenten umsetzen.
• Markdown-Support: Inhalte können bequem in Markdown erstellt werden.

Anwendungsfälle

Jigsaw eignet sich für folgende Einsatzszenarien:

• Projekt- und API-Dokumentationsseiten
• Persönliche Blogs oder Technik-Websites
• Unternehmenspräsentationen und Landingpages für Produkte
• Kleine Portfolio- oder Präsentationsseiten
• Alle Websites, die hohe Anforderungen an Geschwindigkeit und Sicherheit stellen und deren Content wenig dynamisch ist

Voraussetzungen

Vor dem Start stellen Sie bitte Folgendes sicher:

1. ServBay ist installiert und läuft: ServBay sollte auf Ihrem macOS-System installiert und gestartet sein. Es bringt bereits PHP, Composer und Node.js/npm mit – alle sind für Jigsaw erforderlich.
2. Grundlegende Terminal-Kenntnisse: Sie sollten in der Lage sein, grundlegende Befehle im Terminal auszuführen.
3. Basiswissen zu Composer und npm: Die Installation von Jigsaw erfolgt über Composer, für die Frontend-Assets wird npm benötigt.

Installations- und Konfigurationsschritte

Im Folgenden werden alle Schritte zur Installation und Einrichtung eines Jigsaw-Projekts mit ServBay im Detail erklärt.

Schritt 1: Projektverzeichnis anlegen

Öffnen Sie zunächst Ihr Terminal, navigieren Sie in das von ServBay empfohlene Webroot-Verzeichnis /Applications/ServBay/www und erstellen Sie dort einen neuen Unterordner für Ihr Jigsaw-Projekt.

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

Das Projektverzeichnis heißt in unserem Beispiel servbay-jigsaw-demo. Hier werden sämtliche Projektdaten gespeichert.

Schritt 2: Jigsaw-Projekt mit Composer erstellen

Composer ist bereits in ServBay vorinstalliert und vorkonfiguriert. Sie müssen ihn also nicht separat einrichten und können einfach im Terminal Composer-Befehle verwenden. Erstellen Sie das Jigsaw-Projekt im eben erstellten Verzeichnis (/Applications/ServBay/www/servbay-jigsaw-demo):

composer create-project tightenco/jigsaw .

Dieser Befehl lädt die aktuelle Version von Jigsaw und alle erforderlichen PHP-Abhängigkeiten ins aktuelle Verzeichnis (.). Das abschließende . sorgt dafür, dass das Projekt in diesem Ordner und nicht in einem weiteren Unterordner namens jigsaw angelegt wird.

Schritt 3: ServBay-Website konfigurieren

Damit Sie Ihre Jigsaw-Website im Browser aufrufen können, richten Sie in ServBay ein neues Projekt als lokale Website ein.

1. ServBay UI öffnen: Öffnen Sie das ServBay-Panel über das Dock-Icon oder das Menüleisten-Symbol.
2. Zum Tab "Webseiten" navigieren: Klicken Sie in der linken Navigation auf den Bereich „Webseiten“.
3. Neue Website hinzufügen: Klicken Sie unten auf das „+“-Symbol und wählen Sie „Website hinzufügen“.
4. Details eintragen:
   • Name: Geben Sie einen klaren Namen wie ServBay Jigsaw Demo ein.
   • Domain: Legen Sie eine Wunschdomain für den lokalen Zugriff fest. Es empfiehlt sich, die Endung .servbay.demo zu nutzen, z.B. jigsaw-demo.servbay.demo, um Namenskonflikte mit echten Domains zu vermeiden. ServBay leitet solche Domains automatisch auf Ihren lokalen Rechner um.
   • Webseitentyp: Wählen Sie PHP, da Jigsaw für den Build-Prozess PHP benötigt.
   • PHP-Version: Wählen Sie eine installierte und aktuelle PHP-Version aus.
   • Webroot: Dieser Schritt ist essenziell. Jigsaw speichert standardmäßig die generierten statischen Dateien im Unterverzeichnis build_local des Projekts. Deshalb muss das Website-Stammverzeichnis auf diesen Ausgabeordner zeigen: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Speichern und anwenden: Nach Eingabe aller Felder klicken Sie auf „Speichern“. Bestätigen Sie die Abfrage von ServBay, um die Änderungen zu übernehmen. Die Webserver-Konfiguration (Caddy oder Nginx) sowie das HTTPS-Zertifikat werden automatisch aktualisiert.

Schritt 4: Frontend-Abhängigkeiten installieren

Jigsaw nutzt npm zum Verwalten und Kompilieren von Frontend-Assets (etwa CSS-Präprozessoren, SASS, JavaScript-Dateien usw.). Node.js und npm sind in ServBay bereits einsatzbereit.

Installieren Sie die Frontend-Dependencies im Projektverzeichnis (/Applications/ServBay/www/servbay-jigsaw-demo) mit folgendem Befehl:

npm install

Dadurch werden die im package.json angegebenen Node.js-Module in den Ordner node_modules heruntergeladen.

Schritt 5: Jigsaw-Seite bauen

Nachdem sämtliche Abhängigkeiten installiert sind, müssen Sie Ihr Jigsaw-Projekt bauen, um die statische Website zu erzeugen.

Führen Sie im Projektverzeichnis folgenden Befehl aus:

./vendor/bin/jigsaw build

Dieser Befehl erledigt:

1. Verarbeitung der Markdown-Dateien und Blade-Templates im source-Verzeichnis.
2. Ausführung der in der Datei webpack.mix.js definierten Build-Tasks (sofern Laravel Mix durch npm install eingebunden wurde).
3. Ausgabe aller statischen HTML-, CSS-, JS- und weiteren Dateien in das build_local-Verzeichnis.

Schritt 6: Website aufrufen

Ihre fertige Jigsaw-Website liegt nun im Verzeichnis /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Da Ihr Webroot bereits darauf zeigt, können Sie die Website ab sofort über die im dritten Schritt eingerichtete lokale Domain im Browser aufrufen.

Öffnen Sie dafür einfach Ihren Webbrowser und geben Sie die konfigurierte Domain ein, z.B. https://jigsaw-demo.servbay.demo. Dank ServBay ist HTTPS automatisch konfiguriert (über die ServBay User CA). Sie sollten daraufhin die Standard-Willkommensseite von Jigsaw sehen.

Individualisierung & Entwicklung

Das Grundsetup steht. Nun können Sie mit der individuellen Gestaltung Ihrer Jigsaw-Website beginnen.

Inhalte & Templates bearbeiten

• Den Quellcode der Website finden Sie im Ordner source im Projektroot.
• HTML-Layouts und Komponenten werden per Blade-Template umgesetzt und befinden sich typischerweise in source/_layouts und source/_partials.
• Seite-Inhalte werden meist in Markdown angelegt und liegen direkt in source oder dessen Unterordnern (z.B. source/index.md, source/about.md).
• Blogposts kommen in das Verzeichnis source/_posts und werden im Format YYYY-MM-DD-slug.md benannt.

Neue Seiten/Posts anlegen

Für eine neue Seite oder einen Blogbeitrag genügt es, eine weitere Markdown-Datei im source-Verzeichnis bzw. im passenden Unterordner (source/_posts) anzulegen.

Beispiel für source/about.md:

---
title: "Über uns"
description: "Weitere Infos zum ServBay Jigsaw Demo"
---

# Über uns

Dies ist eine About-Seite, erstellt mit Jigsaw.

Hier können Sie Unternehmensinfos, Details zum Team usw. ergänzen.

Eigene Styles & Skripte

Jigsaw-Projekte verwenden meist Laravel Mix (webpack.mix.js) zur Kompilierung der Frontend-Assets.

• Stylesheets (oft SASS/SCSS) liegen im Verzeichnis source/_assets/sass
• JavaScript-Dateien liegen unter source/_assets/js

Sie können die Assets bequem per npm-Skripten im Projektverzeichnis kompilieren:

• npm run dev: Baut die Entwicklungs-Assets mit Source Maps (nicht minifiziert).
• npm run watch: Baut und überwacht automatisch auf Dateiänderungen – ideal während der Entwicklung.
• npm run prod: Produziert minifizierte und optimierte Assets für den Produktivbetrieb.

Wenn Sie z.B. die Datei source/_assets/sass/main.scss anpassen, können Sie mit npm run dev oder npm run watch direkt die neue CSS-Version erzeugen.

Website neu bauen

Wichtiger Hinweis: Immer nach Änderungen an Inhaltsdateien (Markdown) oder Template-Files (Blade) müssen Sie den Jigsaw-Build-Befehl erneut starten, um die Anpassungen zu übernehmen und das build_local-Verzeichnis zu aktualisieren:

./vendor/bin/jigsaw build

Änderungen an Frontend-Assets (SASS, JS) erfordern das Ausführen von npm run dev oder npm run watch zum Neu-Kompilieren der Assets. In den meisten Jigsaw-Projekten übernimmt auch der build-Befehl die Mix-Kompilierung – es hilft aber beim Debuggen, die Abläufe separat zu betrachten.

Hinweise & Tipps

• Build-Output-Verzeichnis: Jigsaw baut für die Entwicklung standardmäßig nach build_local (für Production nach build_production). Achten Sie darauf, dass Sie im ServBay-Webroot auf das richtige Verzeichnis zeigen (für lokale Entwicklung meist build_local).
• Webserver: ServBay nutzt Caddy oder Nginx und liefert die statischen Dateien direkt aus dem build_local-Ordner aus – performant und zuverlässig. Den internen Befehl jigsaw serve brauchen Sie nicht zu verwenden (dieser ist vorrangig für Schnell-Vorschauen gedacht und bietet weniger Funktionalität als die ServBay-Webserver).
• HTTPS: ServBay konfiguriert für .servbay.demo-Domains automatisch HTTPS mit einem eigenen User-CA-Zertifikat. Gegebenenfalls müssen Sie das Zertifikat des ServBay User CA im System vertrauen, um Browserwarnungen zu vermeiden.
• Clean Build: Bei merkwürdigen Build-Problemen hilft oft ein sauberer Build mit ./vendor/bin/jigsaw build --clean.

Häufige Fragen (FAQ)

F: Ich habe eine Markdown-Datei geändert, aber im Browser werden die Änderungen nicht angezeigt?

A: Sie müssen nach Änderungen an Inhalten oder Templates den Befehl ./vendor/bin/jigsaw build im Terminal ausführen, um die Website neu zu bauen.

F: Ich habe eine SCSS-Datei bearbeitet, aber die Styles ändern sich nicht?

A: Nach Änderungen an Frontend-Assets müssen Sie im Projektverzeichnis npm run dev oder npm run watch ausführen, um die Assets neu zu kompilieren.

F: Meine lokale Domain ist nicht erreichbar oder es fehlen Dateien?

A: Prüfen Sie bitte folgendes:

1. Läuft ServBay?
2. Ist die Konfiguration in ServBay korrekt? Sind Domain und Webroot richtig eingestellt (/Applications/ServBay/www/servbay-jigsaw-demo/build_local)?
3. Haben Sie den Build-Befehl ausgeführt (./vendor/bin/jigsaw build) und liegen im build_local-Verzeichnis tatsächlich statische Dateien (z.B. index.html)?

F: Wie kann ich eine Jigsaw-Seite live deployen?

A: Jigsaw erzeugt rein statische Dateien. Das typische Vorgehen:

1. Führen Sie ./vendor/bin/jigsaw build production für einen Production-Build (optimiert) aus.
2. Laden Sie alle Dateien aus dem Ordner build_production bei einem beliebigen Anbieter für statisches Hosting hoch (z.B. Netlify, Vercel, GitHub Pages, diverse Cloudlösungen).

Zusammenfassung

Mit ServBay ist die Installation und Konfiguration des Jigsaw Static Site Generators unter macOS extrem effizient und bequem. ServBay liefert alle nötigen Komponenten (PHP, Composer, Node.js, npm) sowie leistungsstarke lokale Webserver-Konfigurationen. Wenn Sie dieser Anleitung folgen, können Sie Ihr Jigsaw-Projekt im Handumdrehen starten und von den ServBay-Features für optimierte lokale Workflows profitieren.