Modèle de base pour l'utilisation de GitHub Pages dans le cadre de sujets pour les 3OLEN.
- Utilisation des dépendances supportées par GitHub Pages.
- Récupération des sources depuis le dépôt GitHub : téléchargement des sources ou
git clone. - Suppression du
.git(si récupération pargit clone). - Initialisation d'un nouveau dépôt Git :
git init --initial-branch main. - Adaptation des fichiers pour le nouveau projet ; Procédure détaillée.
- Définition du dépôt GitHub :
git remote add origin <url_repository>. git add . && git commit -m "🎉 New GitHub Pages project" && git push -u origin main.
Puisque les sources sont copiées, il est nécessaire d'adapter les différents fichiers pour la cohérence avec le nouveau projet.
Tout ce qui se trouve dans les dossiers bin/dev et docker est lié à l'utilisation de docker afin de définir le
site en local et pouvoir le concevoir et le tester sans avoir besoin d'installer l'environnement GitHub Pages sur la
machine ni de le déployer à chaque modification sur GitHub.
Si vous comptez utiliser Docker, il est nécessaire de modifier le fichier _parameters et les variables :
DOCKER_IMAGE_NAME: Nom de l'image Docker ; à modifier selon le nom du projet.DOCKER_CONTAINER_NAME: Nom du container Docker ; n'est peut-être pas à modifier.
Le détail de l'utilisation de Docker est défini à la section Scripts Docker.
Si vous ne comptez pas utiliser Docker, vous pouvez supprimer ces dossiers.
Pour tester le site en local sans utiliser Docker, il sera nécessaire d'installer :
Puis d'exécuter les mêmes commandes que celles définies dans le fichier entrypoint.
Source : GitHub Pages - Testing your GitHub Pages site locally with Jekyll
L'ensemble du contenu du fichier README.md est à supprimer et à réécrire selon le nouveau projet.
La configuration de Jekyll se trouve dans le fichier _config.yaml ; deux variables sont à modifier :
title: titre du site/projet ; est utilisée dans le<title>HTML.description: description du site/projet.
La page d'accueil (index.html) reprend seulement la description du site/projet. Vous pouvez la modifier avant le commit initial ou le faire plus tard.
Les informations concernant le développement local (avec ou sans Docker) sont définies plus haut.
bin/dev/start- Initialise l'environnement Docker en créant l'image utilisée par le container.
- Crée un container en "one-shot" en se basant sur le
entrypoint.
bin/dev/build- Exécute la commande
jekyll build(par le biais debundler) dans le container Docker. - Il est parfois nécessaire de forcer un build pour que les modifications soient prises en compte, notamment sur la config, le style ou encore le templating dynamique.
- Exécute la commande
Les pages sont définies à la racine des sources du site (dossier docs) ou dans des sous-dossiers, selon la
structuration prévue. Ces pages doivent utiliser l'extension .html ou .md.
⚠️ Le Front Matter est obligatoire pour que ces fichiers soient pris en compte par Jekyll.
La configuration de l'IDE doit être adaptée pour pouvoir associer ces fichiers au langage Liquid pour la coloration
syntaxique et l'autocomplétion.
La suite « Jetbrains » possède un plugin Liquid.
Les _layouts ou les _includes peuvent être définis en tant que fichier .liquid (ou .html.liquid / .md.liquid)
afin d'utiliser la coloration syntaxique et l'autocomplétion pour Liquid de l'IDE.
Il ne reste plus qu'à vous mettre au travail et fournir un site "statique" selon vos besoins !