Résolution des erreurs de build Jekyll pour les sites GitHub Pages

Vous pouvez utiliser les messages d’erreur de build Jekyll pour résoudre les problèmes liés à votre site GitHub Pages.

Qui peut utiliser cette fonctionnalité ?

GitHub Pages est disponible dans les référentiels publics avec GitHub Free et GitHub Free pour les organisations, et dans les référentiels publics et privés avec GitHub Pro, GitHub Team, GitHub Enterprise Cloud et GitHub Enterprise Server.

Dans cet article

Résolution des erreurs de build

Si Jekyll rencontre une erreur lors de la génération de votre site GitHub Pages en local ou sur GitHub Enterprise Server, vous pouvez utiliser des messages d’erreur pour la résoudre. Pour plus d’informations sur les messages d’erreur et comment les afficher, consultez À propos des erreurs de build Jekyll pour les sites GitHub Pages.

Si vous avez reçu un message d’erreur générique, recherchez les problèmes courants.

  • Vous utilisez des plug-ins non pris en charge. Pour plus d’informations, consultez À propos de GitHub Pages et Jekyll.
  • Vous avez changé le paramètre source dans votre fichier _config.yml. Si vous publiez votre site à partir d’une branche, GitHub Pages remplace ce paramètre pendant le processus de génération.
  • Un nom de fichier dans vos fichiers publiés contient un signe deux-points (:) qui n’est pas pris en charge.

Si vous avez reçu un message d’erreur spécifique, consultez les informations de dépannage pour le message d’erreur ci-dessous.

Une fois que vous avez corrigé les erreurs, déclenchez une autre version en poussant les modifications apportées à la branche source de votre site (si vous publiez à partir d’une branche) ou en déclenchant votre workflow GitHub Actions personnalisé (si vous publiez avec GitHub Actions).

Erreur dans le fichier de configuration

Cette erreur signifie que votre site n’a pas pu être généré, car le fichier _config.yml contient des erreurs de syntaxe.

Pour les résoudre, vérifiez que votre fichier _config.yml respecte les règles suivantes :

  • Utilisez des espaces plutôt que des onglets.
  • Ajoutez un espace après les : pour chaque paire clé-valeur, par exemple timezone: Africa/Nairobi.
  • Utilisez uniquement des caractères UTF-8.
  • Mettez entre guillemets les caractères spéciaux comme :, par exemple title: "my awesome site: an adventure in parse errors".
  • Pour les valeurs multilignes, utilisez | pour créer des nouvelles lignes et > pour ignorer les nouvelles lignes.

Pour identifier les erreurs, vous pouvez copier et coller le contenu de votre fichier YAML dans un linter YAML, comme YAML Validator.

Note

If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "Documentation GitHub Actions."

La date n’est pas valide

Cette erreur signifie qu’une des pages de votre site contient une date non valide.

Pour la résoudre, recherchez dans le fichier du message d’erreur et les dispositions du fichier les appels à tous les filtres Liquid associés à la date. Assurez-vous que toutes les variables passées dans les filtres Liquid associés à la date ont des valeurs dans tous les cas et ne passent jamais nil ou "". Pour plus d'informations, voir Filtres dans la documentation de Liquid.

Le fichier n’existe pas dans le répertoire includes

Cette erreur signifie que votre code référence un fichier qui n’existe pas dans votre répertoire _includes.

Pour la résolution, recherchez include dans le fichier du message d’erreur pour voir où vous avez référencé d’autres fichiers comme {% include example_header.html %}. Si des fichiers que vous avez référencés ne se trouvent pas dans le répertoire _includes, copiez ou déplacez les fichiers dans le répertoire _includes.

Le fichier n’est pas correctement codé UTF-8

Cette erreur signifie que vous avez utilisé des caractères non latins, comme 日本語, sans indiquer à l’ordinateur de s’attendre à ces symboles.

Pour la résoudre, forcez l’encodage UTF-8 en ajoutant la ligne suivante à votre fichier _config.yml :

encoding: UTF-8

Langage de colorateur non valide

Cette erreur signifie que vous avez spécifié un colorateur de syntaxe autre que Rouge ou Pygments dans votre fichier de configuration.

Pour la résoudre, mettez à jour votre fichier _config.yml pour spécifier Rouge ou Pygments. Pour plus d’informations, consultez « À propos de GitHub Pages et Jekyll ».

Date de publication non valide

Cette erreur signifie qu’une publication sur votre site contient une date non valide dans le nom de fichier ou l’en-tête YAML.

Pour la résoudre, assurez-vous que toutes les dates sont au format AAAA-MM-JJ HH:MM:SS pour UTC et qu’elles sont issues d’un vrai calendrier. Pour spécifier un fuseau horaire avec un décalage par rapport à UTC, utilisez le format AAAA-MM-DD HH:MM:MM:SS +/-TTTT, comme 2014-04-18 11:30:00 +0800.

Si vous spécifiez un format de date dans votre fichier _config.yml, vérifiez que le format est correct.

Sass ou SCSS non valide

Cette erreur signifie que votre dépôt contient un fichier SAss ou SCSS avec du contenu non valide.

Pour la résoudre, vérifiez le numéro de ligne compris dans le message d’erreur pour trouver le fichier Sass ou SCSS non valide. Pour éviter de nouvelles erreurs, installez un linter Sass ou SCSS pour votre éditeur de texte favori.

Sous-module non valide

Cette erreur signifie que votre dépôt comprend un sous-module qui n’a pas été correctement initialisé.

Pour résoudre les problèmes, commencez par décider si vous voulez utiliser un sous-module, qui est un projet Git à l’intérieur d’un projet Git. Les sous-modules sont parfois créés accidentellement.

Si vous ne voulez pas utiliser de sous-module, supprimez le sous-module, en remplaçant PATH-TO-SUBMODULE par le chemin du sous-module :

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Si vous souhaitez utiliser le sous-module, assurez-vous d’utiliser https:// lors du référencement du sous-module (non http://) et que le sous-module est dans un dépôt public.

YAML non valide dans le fichier de données

Cette erreur signifie qu’un ou plusieurs fichiers du dossier _data contient un fichier YAML non valide.

Pour la résoudre, vérifiez que les fichiers YAML de votre dossier _data suivent ces règles :

  • Utilisez des espaces plutôt que des onglets.
  • Ajoutez un espace après les : pour chaque paire clé-valeur, par exemple timezone: Africa/Nairobi.
  • Utilisez uniquement des caractères UTF-8.
  • Mettez entre guillemets les caractères spéciaux comme :, par exemple title: "my awesome site: an adventure in parse errors".
  • Pour les valeurs multilignes, utilisez | pour créer des nouvelles lignes et > pour ignorer les nouvelles lignes.

Pour identifier les erreurs, vous pouvez copier et coller le contenu de votre fichier YAML dans un linter YAML, comme YAML Validator.

Pour plus d'informations sur les fichiers de données Jekyll, voir Fichiers de données dans la documentation Jekyll.

Erreurs Markdown

Cette erreur signifie que votre dépôt contient des erreurs Markdown.

Pour la résoudre, veillez à utiliser un processeur Markdown pris en charge. Pour plus d’informations, consultez « Définition d’un processeur Markdown pour votre site GitHub Pages avec Jekyll ».

Vérifiez ensuite que le fichier dans le message d’erreur utilise une syntaxe Markdown valide. Pour plus d’informations, consultez « Markdown : Syntaxe » sur Daring Fireball.

Dossier docs manquant

Cette erreur signifie que vous avez choisi le dossier docs d’une branche comme source de publication, alors qu’il n’existe aucun dossier docs à la racine de votre dépôt sur cette branche.

Pour la résoudre, si votre dossier docs a été déplacé par erreur, essayez de ramener le dossier docs à la racine de votre dépôt sur la branche que vous avez choisie pour votre source de publication. Si le dossier docs a été supprimé par erreur, vous pouvez :

  • Utiliser Git pour rétablir ou annuler la suppression. Pour plus d’informations, consultez « git-revert » dans la documentation Git.
  • Créez un dossier docs à la racine de votre dépôt sur la branche que vous avez choisie pour votre source de publication et ajoutez les fichiers sources de votre site au dossier. Pour plus d’informations, consultez « Création de fichiers ».
  • Changez de source de publication. Pour plus d’informations, consultez « Configuration d’une source de publication pour votre site GitHub Pages ».

Sous-module manquant

Cette erreur signifie que votre dépôt comprend un sous-module qui n’existe pas ou qui n’a pas été correctement initialisé.

Pour résoudre les problèmes, commencez par décider si vous voulez utiliser un sous-module, qui est un projet Git à l’intérieur d’un projet Git. Les sous-modules sont parfois créés accidentellement.

Si vous ne voulez pas utiliser de sous-module, supprimez le sous-module, en remplaçant PATH-TO-SUBMODULE par le chemin du sous-module :

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Si vous souhaitez utiliser un sous-module, initialisez-le. Pour plus d’informations, consultez « Outils Git - Sous-modules » dans le manuel Pro Git.

Cette erreur signifie que vous avez des liens permanents relatifs, qui ne sont pas pris en charge par GitHub Pages, dans votre fichier _config.yml.

Les liens permanents sont des URL permanentes qui référencent une page particulière sur votre site. Les liens permanents absolus commencent à la racine du site, tandis que les liens permanents relatifs commencent au dossier contenant la page référencée. GitHub Pages et Jekyll ne prennent plus en charge les liens permanents relatifs. Pour plus d'informations sur les permaliens, voir Permaliens dans la documentation Jekyll.

Pour résoudre cette erreur, supprimez la ligne relative_permalinks de votre fichier _config.yml et remplacez les liens permanents relatifs de votre site par des liens permanents absolus. Pour plus d’informations, consultez « Modification de fichiers ».

Erreur de syntaxe dans la boucle « for »

Cette erreur signifie que votre code comprend une syntaxe non valide dans une déclaration de boucle for Liquid.

Pour la résoudre, vérifiez que toutes les boucles for du fichier dans le message d’erreur ont une syntaxe appropriée. Pour plus d'informations sur la syntaxe correcte des for boucles, voir Tags dans la documentation de Liquid.

Balise mal fermée

Ce message d’erreur signifie que votre code inclut une balise logique qui n’est pas bien fermée. Par exemple, {% capture example_variable %} doit être fermé avec {% endcapture %}.

Pour résoudre ce message d’erreur, vérifiez que toutes les balises logiques du fichier dans le message d’erreur sont bien fermées. Pour plus d'informations, voir Tags dans la documentation de Liquid.

Balise mal terminée

Cette erreur signifie que votre code inclut une balise de sortie qui n’est pas bien terminée. Par exemple, {{ page.title } au lieu de {{ page.title }}.

Pour résoudre ce message d’erreur, vérifiez que toutes les balises de sortie du fichier dans le message d’erreur se terminent par }}. Pour plus d'informations, voir Objets dans la documentation de Liquid.

Erreur de balise inconnue

Cette erreur signifie que votre code contient une balise Liquid non reconnue.

Pour la résoudre, assurez-vous que toutes les balises Liquid dans le fichier du message d’erreur correspondent aux variables par défaut de Jekyll et qu’il n’y a pas de fautes de frappe dans les noms des balises. Pour obtenir la liste des variables par défaut, consultez « Variables » dans la documentation de Jekyll.

Les plug-ins non pris en charge sont une source courante de balises non reconnues. Si vous utilisez un plug-in non pris en charge dans votre site en générant votre site en local et en poussant vos fichiers statiques vers GitHub Enterprise Server, assurez-vous que le plug-in n’introduit pas de balises qui ne sont pas dans les variables par défaut de Jekyll. Pour une liste des plug-ins pris en charge, consultez À propos de GitHub Pages et Jekyll.