Installation et configuration de Jigsaw dans l’environnement ServBay

Présentation

Ce document a pour objectif de vous guider dans l'installation et la configuration du générateur de site statique Jigsaw au sein de l’environnement web local puissant ServBay. ServBay offre un environnement intégré pour des stacks variés comme PHP et Node.js, simplifiant grandement le processus de création des projets Jigsaw. Grâce à ServBay, vous pouvez facilement configurer des domaines locaux, le HTTPS, ainsi qu’un serveur web performant pour vos projets Jigsaw, vous permettant ainsi de vous concentrer sur le développement du contenu de votre site.

Qu’est-ce que Jigsaw ?

Jigsaw est un générateur de sites statiques construit à partir de composants Laravel, développé par la société Tighten. Il exploite la puissance et la flexibilité du moteur de template Blade de Laravel, tout en utilisant des fichiers Markdown pour générer un site HTML statique pur. Jigsaw est idéal pour créer des sites de documentation, des blogs, des pages marketing ou tout site ne nécessitant pas de base de données ou de traitement dynamique côté serveur. Ses principaux atouts sont :

• Utilisation d’outils familiers : Si vous connaissez Laravel ou Blade, la prise en main de Jigsaw sera simple et rapide.
• Performance et sécurité : Les sites statiques générés sont très rapides à charger et, ne comportant aucun code exécuté côté serveur, ils offrent une sécurité accrue.
• Templates flexibles : Grâce à Blade, il est possible de construire des mises en page et des composants complexes.
• Support Markdown : Rédaction de contenu simplifiée.

Cas d’utilisation

Jigsaw convient particulièrement aux situations suivantes :

• Sites de documentation de projet ou d’API
• Blogs personnels ou plateformes de partage technique
• Pages de vente ou de présentation (landing pages) pour entreprises ou produits
• Petits sites vitrines
• Tout site à contenu relativement stable, avec de fortes exigences de performance et sécurité

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

1. ServBay installé et en cours d’exécution : Vous devez avoir installé et démarré ServBay sur macOS. ServBay inclut déjà PHP, Composer et Node.js/npm, nécessaires à l’installation et l’exécution de Jigsaw.
2. Notions de base sur l’utilisation du terminal : Vous aurez à exécuter certaines commandes dans le terminal.
3. Compréhension élémentaire de Composer et npm : L’installation de Jigsaw s’appuie sur Composer et la compilation des assets front-end s’effectue par npm.

Étapes d’installation et de configuration

Cette section présente en détail les étapes pour installer et configurer un projet Jigsaw dans l’environnement ServBay.

Étape 1 : Créer le répertoire du projet

Commencez par ouvrir votre terminal. Placez-vous dans le répertoire racine dédié aux sites web recommandé par ServBay (/Applications/ServBay/www) et créez un nouveau sous-répertoire pour votre projet Jigsaw.

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

Nous avons nommé le répertoire du projet servbay-jigsaw-demo. Tous les fichiers du projet y seront stockés.

Étape 2 : Créer un projet Jigsaw via Composer

ServBay intègre déjà Composer et vous permet d’utiliser la commande composer dans n’importe quel terminal. Placez-vous dans le répertoire que vous venez de créer (/Applications/ServBay/www/servbay-jigsaw-demo) et lancez la commande suivante pour créer un projet Jigsaw :

composer create-project tightenco/jigsaw .

Cette commande télécharge la dernière version de Jigsaw ainsi que toutes ses dépendances PHP dans le répertoire courant (.). Notez que le point à la fin indique que le projet doit être créé ici, et non dans un sous-dossier jigsaw.

Étape 3 : Configurer le site dans ServBay

Pour accéder à votre site Jigsaw depuis un navigateur, vous devez configurer un site local dans ServBay.

1. Ouvrir l’interface de ServBay : Double-cliquez sur l’icône de l’application ou ouvrez le panneau de contrôle via la barre de menu.
2. Accéder à l’onglet « Sites » : Dans le menu à gauche, cliquez sur l’onglet « Sites ».
3. Ajouter un nouveau site : Cliquez sur le bouton « + » en bas de l’interface et choisissez « Ajouter un site ».
4. Configurer les paramètres du site :
   • Nom : Saisissez un nom facilement reconnaissable, par exemple ServBay Jigsaw Demo.
   • Domaine : Indiquez le domaine local que vous souhaitez utiliser. Nous recommandons le suffixe .servbay.demo pour éviter tout conflit avec de vrais domaines, par exemple jigsaw-demo.servbay.demo. ServBay s’occupera de la résolution du domaine local.
   • Type de site : Sélectionnez PHP (la construction de Jigsaw requiert l’environnement PHP).
   • Version PHP : Choisissez une version PHP installée dans ServBay, de préférence une version stable et récente.
   • Répertoire racine du site : Cette étape est cruciale. Les fichiers générés par Jigsaw sont placés par défaut dans le dossier build_local à la racine du projet. Le répertoire racine du site doit donc pointer vers ce dossier de sortie : /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Enregistrer et appliquer : Après avoir complété toutes les informations, cliquez sur « Enregistrer ». ServBay vous demandera de confirmer l’application des modifications. Acceptez, et ServBay mettra automatiquement à jour la configuration du serveur web (Caddy ou Nginx), ainsi que l’activation du HTTPS.

Étape 4 : Installer les dépendances front-end

Un projet Jigsaw utilise généralement npm pour gérer et compiler les assets front-end (par exemple, SASS, fichiers JavaScript, etc.). Node.js et npm sont également préinstallés dans ServBay.

Dans le répertoire du projet (/Applications/ServBay/www/servbay-jigsaw-demo), exécutez la commande suivante pour installer les dépendances front-end :

npm install

Cela lira le fichier package.json situé à la racine du projet et téléchargera les modules Node.js nécessaires dans le dossier node_modules.

Étape 5 : Générer le site Jigsaw

Une fois toutes les dépendances installées, il faut construire le site statique à l’aide de la commande suivante :

./vendor/bin/jigsaw build

Cette commande va :

1. Traiter les fichiers Markdown et les templates Blade présents dans le dossier source.
2. Exécuter les tâches de compilation définies dans webpack.mix.js (sous réserve que Laravel Mix ait été installé via npm install).
3. Exporter le résultat final (HTML, CSS, JS et autres assets) dans le dossier build_local.

Étape 6 : Accéder à votre site

À cette étape, les fichiers statiques de votre site Jigsaw sont générés et disponibles dans /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Puisque le répertoire racine de votre site a été configuré sur ce dossier dans ServBay, vous pouvez désormais accéder à votre site via le domaine local paramétré plus tôt.

Ouvrez votre navigateur et visitez l’URL, par exemple https://jigsaw-demo.servbay.demo. ServBay gère automatiquement le certificat HTTPS (via ServBay User CA) et vous devriez voir la page d’accueil par défaut de Jigsaw.

Personnalisation et développement

Votre environnement de base est maintenant prêt, vous pouvez personnaliser le contenu et le style de votre site Jigsaw selon vos besoins.

Modifier le contenu et les templates

• Le code source du site est dans le dossier source à la racine du projet.
• Les layouts et composants HTML sont définis via Blade dans les dossiers source/_layouts et source/_partials.
• Le contenu des pages est généralement rédigé en Markdown dans source ou ses sous-répertoires (ex. source/index.md, source/about.md).
• Les articles de blog sont placés dans source/_posts et nommés selon le format YYYY-MM-DD-slug.md.

Ajouter une nouvelle page ou un article

Pour ajouter une page ou un nouvel article, il suffit de créer un fichier Markdown dans source ou l’un de ses sous-dossiers (comme source/_posts).

Par exemple, pour créer source/about.md :

---
title: "À propos de nous"
description: "En savoir plus sur ServBay Jigsaw Demo"
---

# À propos de nous

Ceci est une page « À propos » construite avec Jigsaw.

Vous pouvez disposer ici d’une présentation de votre entreprise, de votre équipe, etc.

Personnalisation des styles et scripts

Les projets Jigsaw utilisent en général Laravel Mix (webpack.mix.js) pour la compilation des assets front-end.

• Les fichiers de style (souvent SASS/SCSS) se trouvent dans source/_assets/sass.
• Les fichiers JavaScript se trouvent dans source/_assets/js.

Dans le répertoire du projet, utilisez les scripts npm suivants pour compiler ces assets :

• npm run dev : compile les assets en mode développement (avec source maps, non compressé).
• npm run watch : compile en mode développement et surveille les fichiers pour une recompilation automatique – idéal pendant le développement.
• npm run prod : compile les assets pour la production (compression et optimisation).

Par exemple, après modification de source/_assets/sass/main.scss, lancez npm run dev ou npm run watch pour générer le CSS correspondant.

Reconstruire le site

À noter : Après modification de fichiers contenu (Markdown) ou templates (Blade) dans le dossier source, il faut toujours relancer la commande de build Jigsaw pour mettre à jour les fichiers statiques dans build_local :

./vendor/bin/jigsaw build

Si vous avez modifié des assets front-end (SASS, JS), lancez npm run dev ou npm run watch pour compiler à nouveau ces fichiers. Dans la majorité des projets Jigsaw, la commande build déclenche aussi la compilation Mix, mais distinguer le process facilite le debug.

Points importants

• Répertoire de sortie : Le build Jigsaw va par défaut dans build_local (développement) ou build_production (production). Assurez-vous que le répertoire racine du site dans ServBay pointe vers celui souhaité (généralement build_local en développement).
• Serveur web : ServBay utilise Caddy ou Nginx pour servir directement les fichiers statiques de build_local. Vous n’avez donc pas besoin d’utiliser la commande intégrée jigsaw serve (principalement utile pour un aperçu rapide, mais moins performant que ServBay).
• HTTPS : ServBay configure automatiquement le HTTPS pour les domaines en .servbay.demo via ServBay User CA. Il se peut que vous deviez faire confiance au certificat User CA dans votre système pour éviter les avertissements du navigateur.
• Build propre : Si vous rencontrez des problèmes de construction, lancez la commande ./vendor/bin/jigsaw build --clean pour un build complet et nettoyé.

FAQ (Foire aux questions)

Q : J’ai modifié un fichier Markdown mais je ne vois pas le changement dans le navigateur ?

R : Après chaque modification de contenu ou de template, exécutez la commande ./vendor/bin/jigsaw build dans le terminal pour rebâtir le site.

Q : Après modification d’un fichier SCSS, le style du site ne change pas ?

R : Après chaque changement d’asset front-end, lancez npm run dev ou npm run watch dans le projet pour recompiler les assets.

Q : Mon domaine local affiche « inaccessible » ou « fichier introuvable » ?

R : Vérifiez les points suivants :

1. Assurez-vous que ServBay est bien en fonctionnement.
2. Vérifiez la configuration du site dans ServBay : le domaine est-il correct ? Le répertoire racine pointe-t-il bien vers /Applications/ServBay/www/servbay-jigsaw-demo/build_local ?
3. Avez-vous lancé la commande ./vendor/bin/jigsaw build ? Vérifiez que des fichiers statiques (comme index.html) sont bien présents dans le dossier build_local.

Q : Comment déployer un site Jigsaw ?

R : Jigsaw génère uniquement des fichiers statiques. La procédure habituelle est :

1. Générer le build de production en lançant ./vendor/bin/jigsaw build production (ce process applique généralement plus d’optimisations).
2. Uploadez tous les fichiers contenus dans le dossier build_production chez n’importe quel hébergeur supportant les sites statiques (Netlify, Vercel, GitHub Pages, solutions cloud, etc.).

Conclusion

Grâce à ServBay, installer et configurer le générateur de site statique Jigsaw sous macOS devient simple et rapide. ServBay vous fournit tout l’environnement requis (PHP, Composer, Node.js, npm) ainsi qu’une configuration et une gestion locales avancées du serveur web. En suivant ce guide, vous pouvez lancer très rapidement des projets Jigsaw, tout en profitant des nombreuses fonctionnalités de ServBay pour optimiser vos workflows de développement local.