Construire son site Jekyll en local

Voir le rendu final avant de publier, sans attendre GitHub

Construire son site Jekyll en local

Installer Ruby et Jekyll pour prévisualiser votre site de documentation sur votre machine, avec rechargement automatique à chaque modification.

Durée :
Difficulté :

Pré-requis :

Logiciels :

Machines/Outils :

Documentation réalisée à 60% 60
Créée par :  Adrien Bracq

Pourquoi construire en local

L’édition depuis GitHub (tutoriel précédent) ne montre pas le rendu final avec le vrai thème du site. En local, jekyll serve reconstruit le site à chaque sauvegarde et l’affiche dans votre navigateur en quelques secondes — vous voyez immédiatement le résultat, sans rien publier.

Installer Ruby et Bundler

Téléchargez et installez Ruby via RubyInstaller (cochez l’option qui ajoute Ruby au PATH pendant l’installation). Redémarrez l’ordinateur, puis dans un terminal :

ruby -v
gem install bundler

Avec Homebrew :

brew install ruby
gem install bundler

sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev
gem install bundler
  Pas de droits administrateur ?

Si vous ne pouvez pas installer de paquets système (pas de sudo), installez Ruby en espace utilisateur avec rbenv (github.com/rbenv/rbenv) — plus long à mettre en place, mais ne nécessite aucun droit root.

Installer les dépendances du projet

bundle install

Dans un terminal, à la racine de votre repo cloné :

bundle install

Ça installe toutes les gems nécessaires (Jekyll, le thème, etc.), listées dans le fichier Gemfile du template.

  Erreur de permission sur /var/lib/gems ou /usr/lib/ruby

Sans droits root, Bundler ne peut pas écrire dans le dossier système des gems. Configurez-le pour installer localement au projet à la place :

bundle config set --local path 'vendor/bundle'
bundle install

Le dossier vendor/ est déjà ignoré par Git (voir .gitignore), ça ne pollue pas votre repo.

Lancer le serveur local

jekyll serve

bundle exec jekyll serve

Ouvrez ensuite http://localhost:4000 dans votre navigateur. Le site se recharge automatiquement à chaque fichier modifié et sauvegardé. Ctrl+C dans le terminal pour arrêter le serveur.

Résolution de problèmes

Symptôme Cause probable Solution
bundle: commande introuvable alors que l’installation semblait réussie La gem bundler est installée dans un dossier absent du PATH (fréquent sans droits root, dossier type ~/.local/share/gem/ruby/<version>/bin) Ajoutez ce dossier au PATH : export PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin" — puis ajoutez cette ligne à ~/.bashrc pour que ce soit permanent
bundle install échoue avec une erreur de permission sur un dossier système Pas de droits root pour écrire dans le dossier de gems partagé Voir l’encart ci-dessus : configurez bundle config set --local path 'vendor/bundle'
Un terminal ne voit ni ruby ni bundle alors qu’un autre terminal les voit Le terminal utilisé tourne en mode sh non interactif (ne charge pas ~/.bashrc), ou (sous Linux avec VSCode installé en Flatpak) le terminal intégré tourne dans le bac à sable Flatpak, isolé du système hôte Essayez exec bash -l ; si le souci persiste avec VSCode en Flatpak, réinstallez-le en .deb/.rpm natif, ou utilisez flatpak-spawn --host bash -l
Le site build mais une page affiche une erreur ou ne s’affiche pas Erreur dans le front matter YAML (indentation, guillemets manquants) Lisez le message d’erreur affiché dans le terminal au moment du build, il indique généralement le fichier en cause

Exercice

Installez Ruby et Bundler si ce n’est pas déjà fait, lancez bundle exec jekyll serve sur votre repo, et vérifiez que http://localhost:4000 affiche bien votre site avec vos dernières modifications.

Contents