Jigsaw installeren en configureren in de ServBay-omgeving

Overzicht

Dit document begeleidt je stap voor stap bij het installeren en configureren van Jigsaw, een krachtige statische site generator, binnen de lokale webontwikkelomgeving ServBay. ServBay biedt een geïntegreerde omgeving voor technologieën als PHP en Node.js, waardoor het opzetten van een Jigsaw-project sterk wordt vereenvoudigd. Met ServBay configureer je probleemloos lokale domeinen, HTTPS én een efficiënte webserver voor je Jigsaw-projecten, zodat jij je volledig kunt richten op het ontwikkelen van de site-inhoud.

Wat is Jigsaw?

Jigsaw is een statische site generator gebouwd op Laravel-componenten, ontwikkeld door Tighten. Het maakt gebruik van de krachtige en flexibele Blade-template engine van Laravel en combineert deze met Markdown-bestanden om volledig statische HTML-websites te genereren. Jigsaw is uitermate geschikt voor documentatiesites, blogs, marketingpagina's of iedere website waar geen backend database of dynamische serverlogica voor nodig is. Belangrijkste voordelen:

• Werken met vertrouwde tools: Als je bekend bent met Laravel of Blade-templates, is Jigsaw zeer toegankelijk.
• Snelheid en veiligheid: Gemaakte sites laden razendsnel en zijn extra veilig doordat er geen server-side code wordt uitgevoerd.
• Flexibele templates: Dankzij Blade-templates kun je eenvoudig complexe lay-outs en herbruikbare componenten maken.
• Markdown-ondersteuning: Schrijven van sitecontent gaat snel en eenvoudig.

Toepassingen

Jigsaw is ideaal in deze situaties:

• Projectdocumentatie of API-documentatie
• Persoonlijke blogs of technische kennisdeling
• Marketing-landingspagina's voor bedrijven of producten
• Kleine presentatiesites
• Elke site met hoge eisen aan snelheid, veiligheid en een grotendeels vaste inhoud

Vereisten

Voordat je begint, zorg dat je aan het volgende voldoet:

1. ServBay geïnstalleerd en gestart: ServBay moet draaien op je macOS-systeem. ServBay bevat direct PHP, Composer en Node.js/npm, essentieel voor Jigsaw.
2. Basiskennis terminalgebruik: Je moet enkele commando's via de terminal uitvoeren.
3. Basiskennis van Composer & npm: Jigsaw wordt geïnstalleerd via Composer, het bouwen van frontend-assets gebeurt via npm.

Stappenplan voor installatie en configuratie

Hieronder vind je het stapsgewijze proces om een Jigsaw-project op te zetten in ServBay.

Stap 1: Maak de projectmap aan

Open je terminal en ga naar de door ServBay aanbevolen webroot: /Applications/ServBay/www. Maak daar een submap voor je Jigsaw-project.

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

We noemen de projectmap servbay-jigsaw-demo. Hierin bewaar je alle projectbestanden.

Stap 2: Maak een Jigsaw-project aan met Composer

ServBay heeft Composer al geïnstalleerd en geconfigureerd, dus je kunt direct composer-commando's uitvoeren vanuit je terminal. Maak in je zojuist aangemaakte projectmap (/Applications/ServBay/www/servbay-jigsaw-demo) het Jigsaw-project aan met:

composer create-project tightenco/jigsaw .

Dit commando downloadt de nieuwste versie van Jigsaw en alle noodzakelijke PHP-afhankelijkheden naar de huidige map (.). De punt aan het einde geeft aan dat het project in de bestaande map geplaatst wordt in plaats van in een nieuwe submap.

Stap 3: Configureer de ServBay-website

Om je Jigsaw-site via de browser te bezoeken, moet je het project als lokale website instellen in ServBay.

1. Open ServBay UI: Open de ServBay-app met een dubbelklik of via de menubalk.
2. Navigeer naar 'Websites': Klik in de zijbalk op het tabblad 'Websites'.
3. Voeg een nieuwe site toe: Klik op de '+' onderin en kies 'Website toevoegen'.
4. Vul de websitegegevens in:
   • Naam: Geef een duidelijke naam, bijvoorbeeld ServBay Jigsaw Demo.
   • Domein: Stel het lokale domein in waarmee je de site bezoekt. Gebruik bij voorkeur de .servbay.demo-extensie, zoals jigsaw-demo.servbay.demo, om conflicten te voorkomen. ServBay koppelt deze automatisch naar localhost.
   • Site Type: Kies PHP, omdat Jigsaw PHP gebruikt voor het builden.
   • PHP-versie: Selecteer een van de beschikbare PHP-versies in ServBay, bij voorkeur de meest recente stabiele.
   • Website root directory: Dit is cruciaal. Statische bestanden die Jigsaw bouwt komen standaard terecht in build_local binnen het project, dus stel dit pad in als webroot: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Opslaan en toepassen: Klik op 'Opslaan' als alles is ingevuld. Bevestig bij de melding. ServBay past vervolgens automatisch de webserverconfiguratie aan (Caddy of Nginx) en regelt HTTPS.

Stap 4: Installeer frontend-afhankelijkheden

Jigsaw-projecten gebruiken meestal npm voor het beheren en builden van frontend-assets (zoals SASS, JavaScript). ServBay bevat direct de benodigde Node.js- en npm-tools.

Voer in je projectmap (/Applications/ServBay/www/servbay-jigsaw-demo) het volgende uit:

npm install

npm leest daarbij het package.json-bestand en installeert de benodigde modules in de map node_modules.

Stap 5: Bouw je Jigsaw-website

Na het installeren van alle afhankelijkheden bouw je de statische sitebestanden van Jigsaw.

Voer in je projectmap dit commando uit:

./vendor/bin/jigsaw build

Dit commando:

1. Verwerkt alle Markdown-bestanden en Blade-templates in de source-map.
2. Start de taken uit webpack.mix.js (bij gebruik van Laravel Mix via npm).
3. Zet het resultaat (statische HTML, CSS, JS, assets) in de map build_local.

Stap 6: Site bekijken

Alle gegeneerde statische bestanden staan nu in /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Omdat je zojuist in ServBay het webrootpad hierheen wees, kun je je site nu in de browser bekijken via het eerder ingestelde domein.

Open je webbrowser en bezoek bijvoorbeeld https://jigsaw-demo.servbay.demo. ServBay regelt automatisch de lokale HTTPS-certificaten (via ServBay User CA). Je ziet nu de standaard Jigsaw welkomstpagina.

Aanpassen en ontwikkelen

Nu alle basis staat, kun je de content en styling van je Jigsaw-site naar wens aanpassen.

Bewerk content en templates

• De bronbestanden van je site vind je in de source-map in de projectroot.
• HTML-layouts en componenten staan als Blade-templates in source/_layouts en source/_partials.
• Contentpagina's schrijf je in Markdown, bijvoorbeeld in source/index.md, source/about.md, etc.
• Blogposts plaats je meestal in source/_posts, volgens het YYYY-MM-DD-slug.md format.

Nieuwe pagina of artikel toevoegen

Een nieuwe pagina of blogpost maak je eenvoudig aan door een nieuw Markdown-bestand te creëren in de juiste directory.

Bijvoorbeeld, maak een nieuw bestand aan: source/about.md:

---
title: "Over ons"
description: "Lees meer over ServBay Jigsaw Demo"
---

# Over ons

Dit is een About-pagina gemaakt met Jigsaw.

Hier kun je bijvoorbeeld bedrijfsinformatie of een teampagina toevoegen.

Eigen stijlen en scripts toevoegen

Jigsaw-projecten gebruiken vaak Laravel Mix (webpack.mix.js) voor het builden van frontend-assets.

• Stylesheets (meestal SASS/SCSS) staan in source/_assets/sass.
• JavaScript-bestanden in source/_assets/js.

Compileer de assets via npm-scripts, bijvoorbeeld:

• npm run dev: Maakt niet-geoptimaliseerde development-builds met sourcemaps.
• npm run watch: Zoals hierboven, maar herbouwt automatisch bij wijzigingen.
• npm run prod: Maakt geoptimaliseerde, productieklare assets.

Pas bijvoorbeeld source/_assets/sass/main.scss aan en draai daarna npm run dev of npm run watch voor het genereren van een nieuwe CSS-file.

Website opnieuw bouwen

Belangrijk: Iedere keer als je content (Markdown) of templates (Blade) in de source-map wijzigt, moet je opnieuw de build uitvoeren voor een bijgewerkte statische site in build_local:

./vendor/bin/jigsaw build

Voor aanpassingen aan frontend-assets (SASS, JS) gebruik je npm run dev of npm run watch om te hercompileren. In de meeste Jigsaw-projecten triggert het build-commando van Jigsaw ook de Mix-build, maar het apart uitvoeren kan helpen bij het oplossen van issues.

Let op

• Build-directory: Jigsaw bouwt standaard naar build_local (development) en build_production (productie). Let er bij ServBay op dat je webroot wijst naar de gewenste output-map (voor lokale ontwikkeling meestal build_local).
• Webserver: ServBay gebruikt Caddy of Nginx om rechtstreeks statische bestanden uit build_local te serveren – dat is snel en efficiënt. Het gebruik van jigsaw serve is doorgaans niet nodig (die is vooral bedoeld voor een snelle preview en biedt minder features dan de ServBay-server).
• HTTPS: ServBay regelt automatisch HTTPS voor .servbay.demo-domeinen met een eigen User CA. Je dient mogelijk het ServBay User CA-certificaat te vertrouwen om browser-waarschuwingen te voorkomen.
• Clean build: Heb je vreemde buildproblemen? Voer dan eens een schone build uit met ./vendor/bin/jigsaw build --clean.

Veelgestelde vragen (FAQ)

Vraag: Ik heb een Markdown-bestand aangepast, maar zie geen wijziging in de browser?

Antwoord: Je moet na iedere wijziging in content of templates het commando ./vendor/bin/jigsaw build uitvoeren om de site opnieuw te genereren.

Vraag: Ik heb een SCSS-bestand aangepast, maar de styling is niet bijgewerkt?

Antwoord: Na aanpassen van assets moet je binnen je projectmap npm run dev of npm run watch draaien om de CSS/JS-assets opnieuw te genereren.

Vraag: Mijn lokale domein is niet bereikbaar of bestanden worden niet gevonden?

Antwoord: Controleer het volgende:

1. Draait ServBay?
2. Staan de juiste instellingen in ServBay? Klopt het domein? Staan webroot naar /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Heb je ./vendor/bin/jigsaw build succesvol uitgevoerd en is er daadwerkelijk een index.html (en andere bestanden) in de map build_local?

Vraag: Hoe publiceer ik mijn Jigsaw-website?

Antwoord: Jigsaw genereert zuivere statische bestanden. Het deployproces is doorgaans:

1. Draai ./vendor/bin/jigsaw build production voor een geoptimaliseerde production build.
2. Upload de gehele inhoud van build_production naar een statische hostingprovider (zoals Netlify, Vercel, GitHub Pages, diverse cloudopslagdiensten, enz.).

Samenvatting

Met ServBay wordt het opzetten en configureren van Jigsaw voor statische sites op macOS extreem makkelijk en efficiënt. ServBay biedt een complete stack (PHP, Composer, Node.js, npm) én krachtige tools voor lokale webserverconfiguratie. Volg deze handleiding en start snel je Jigsaw-project. Profiteer van de uitgebreide mogelijkheden van ServBay om je lokale development-ervaring verder te optimaliseren.