À propos de GitHub Pages et Jekyll

Jekyll est un générateur de site statique avec une prise en charge intégrée de 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. Pour plus d’informations, consultez « Plans de GitHub ».

GitHub Pages utilise désormais GitHub Actions pour exécuter la version de Jekyll. Lorsque vous utilisez une branche comme source de votre version, GitHub Actions doit être activé dans votre référentiel si vous souhaitez utiliser le flux de travail Jekyll prédéfini. Comme alternative, si GitHub Actions n’est pas disponible ou désactivé, l’ajout d’un fichier .nojekyll à la racine de votre branche source contournera le processus de version de Jekyll et déploiera le contenu directement. Pour plus d'informations sur l'activation des GitHub Actions, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Dans cet article

À propos de Jekyll

Jekyll est un générateur de site statique avec une prise en charge intégrée de GitHub Pages et un processus de génération simplifié. Jekyll prend les fichiers Markdown et HTML et crée un site web statique complet en fonction de vos choix de dispositions. Jekyll prend en charge Markdown et Liquid, langage de modèle qui charge du contenu dynamique sur votre site. Pour plus d’informations, consultez Jekyll.

Jekyll n’est pas officiellement pris en charge pour Windows. Pour plus d’informations, consultez Jekyll sur Windows dans la documentation de Jekyll.

Nous recommandons d’utiliser Jekyll avec GitHub Pages. Si vous préférez, vous pouvez utiliser d’autres générateurs de sites statiques ou personnaliser votre propre processus de génération en local ou sur un autre serveur. Pour plus d’informations, consultez « À propos de GitHub Pages ».

Configuration de Jekyll dans votre site GitHub Pages

Vous pouvez configurer la plupart des paramètres Jekyll, comme le thème et les plug-ins de votre site, en modifiant votre fichier _config.yml. Pour plus d’informations, consultez Configuration dans la documentation de Jekyll.

Certains paramètres de configuration ne peuvent pas être modifiés pour les sites GitHub Pages.

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

Par défaut, Jekyll ne génère pas de fichiers ni de dossiers qui :

Se trouvent dans un dossier appelé /node_modules ou /vendor
Commencent par _, . ou #
Se terminent par ~
Sont exclus par le paramètre exclude de votre fichier de configuration

Si vous souhaitez que Jekyll traite l’un de ces fichiers, vous pouvez utiliser le paramètre include dans votre fichier de configuration.

En-tête

Pour définir des variables et des métadonnées, telles qu’un titre et une mise en page, pour une page ou une publication de votre site, vous pouvez ajouter des pages liminaires YAML en haut de n’importe quel fichier Markdown ou HTML. Pour plus d’informations, consultez « Pages liminaires » dans la documentation de Jekyll.

Vous pouvez ajouter site.github à une publication ou une page pour ajouter des métadonnées de référence de dépôt à votre site. Pour plus d’informations, consultez Utilisation de site.github dans la documentation sur les métadonnées de Jekyll.

Thèmes

Vous pouvez ajouter un thème Jekyll à votre site GitHub Pages pour personnaliser son apparence. Pour plus d’informations, consultez Thèmes dans la documentation de Jekyll.

Vous pouvez ajouter un thème pris en charge à votre site dans GitHub. Pour plus d’informations, consultez Thèmes pris en charge sur le site GitHub Pages et Ajout d’un thème à votre site GitHub Pages avec Jekyll.

Pour utiliser tout autre thème Jekyll open source hébergé sur GitHub, vous pouvez ajouter le thème manuellement. Pour plus d’informations, consultez Thèmes hébergés sur GitHub et Ajout d’un thème à votre site GitHub Pages avec Jekyll.

Vous pouvez remplacer les valeurs par défaut de votre thème en modifiant les fichiers du thème. Pour plus d’informations, consultez la documentation de votre thème et Remplacement des valeurs par défaut de votre thème dans la documentation de Jekyll.

Plug-ins

Vous pouvez télécharger ou créer des plug-ins Jekyll pour étendre les fonctionnalités de Jekyll pour votre site. Par exemple, le plug-in jemoji vous permet d’utiliser l’emoji GitHub dans n’importe quelle page de votre site de la même façon que vous le feriez sur GitHub. Pour plus d’informations, consultez Plug-ins dans la documentation de Jekyll.

GitHub Pages utilise des plug-ins qui sont activés par défaut et qui ne peuvent pas être désactivés :

Vous pouvez activer des plug-ins supplémentaires en ajoutant le gem du plug-in au paramètre plugins de votre fichier _config.yml. Pour plus d’informations, consultez Configuration dans la documentation de Jekyll.

Pour obtenir la liste des plug-ins pris en charge, consultez Versions des dépendances sur le site GitHub Pages. Pour plus d’informations sur l’utilisation d’un plug-in spécifique, consultez la documentation du plug-in.

Tip

Vous pouvez vous assurer d’utiliser la dernière version de tous les plug-ins en gardant à jour la gemme GitHub Pages. Pour plus d’informations, consultez Test de votre site GitHub Pages localement avec Jekyll et Versions des dépendances sur le site GitHub Pages.

GitHub Pages ne peut pas générer de sites avec des plug-ins non pris en charge. Si vous souhaitez utiliser des plug-ins non pris en charge, générez votre site en local, puis poussez les fichiers statiques de votre site vers GitHub.

Mise en surbrillance de la syntaxe

Pour faciliter la lecture de votre site, les extraits de code sont en couleur sur les sites GitHub Pages de la même façon qu’ils sont en couleur sur GitHub. Pour plus d’informations sur la coloration syntaxique sur GitHub, consultez Création et mise en évidence de blocs de code.

Par défaut, les blocs de code de votre site sont colorés par Jekyll. Jekyll utilise le surligneur Rouge, qui est compatible avec Pygments). Si vous spécifiez Pygments dans votre fichier _config.yml, Rouge sera utilisé à la place comme solution de repli. Jekyll ne peut pas utiliser d’autres colorateurs de syntaxe et vous obtiendrez un avertissement de génération de page si vous spécifiez un autre colorateur de syntaxe dans votre fichier _config.yml. Pour plus d’informations, consultez « À propos des erreurs de build Jekyll pour les sites GitHub Pages ».

Si vous voulez utiliser un autre surligneur, par exemple highlight.js, vous devez désactiver la coloration syntaxique de Jekyll en mettant à jour le fichier _config.yml de votre projet.

kramdown:
  syntax_highlighter_opts:
    disable : true

Si votre thème n’inclut pas de CSS pour la coloration syntaxique, vous pouvez générer le CSS de coloration syntaxique de GitHub et l’ajouter au fichier style.css de votre projet.

rougify style github > style.css

Création de votre site en local

Si vous publiez à partir d’une branche, les changements de votre site sont publiés automatiquement quand ils sont fusionnés dans la source de publication de votre site. Si vous publiez à partir d’un workflow GitHub Actions personnalisé, les changements sont publiés quand votre workflow est déclenché (généralement via une poussée vers la branche par défaut). Si vous voulez d’abord afficher un aperçu de vos changements, vous pouvez faire les changements localement au lieu de les faire sur GitHub. Ensuite, testez votre site localement. Pour plus d’informations, consultez « Test de votre site GitHub Pages localement avec Jekyll ».