Déployer un site web statique Hugo sur Github Pages
- EN
- FR
# Dernière mise à jour : 01/11/2023 #
Le site que vous consultez est constitué d’un site web statique Hugo hébergé sur Github :
Github fournit la possibilité d’exposer un site web statique pour chaque dépôt public du compte. Il suffit d’avoir :
- Du html+css dans le dépôt ;
- La fonctionnalité Github Pages activée.
Le code statique de chaque dépôt sera alors accessible à l’url : https://MONLOGINGITHUB.github.io/MONDEPOT/
Hugo quand à lui est un générateur de sites web statiques : On écrit des pages en markdown, on lance Hugo, et il génère tout le html et la structure de site que Github exposera.
Liste des mises à jour :
- 01/11/2023 : Mise à jour du script d’action avec la dernière version disponible sur Hugo - hosting on github.
- 19/02/2022 : Je suis passé au thème Anubis plus léger et épuré.
- 06/02/2022 : Mise à jour du script d’action avec la dernière version disponible sur Hugo - hosting on github.
Mode opératoire :
Hugo
Installation
Sous Ubuntu la version dispo dans les dépôts est dépassée. Le plus simple est d’aller récupérer le dernier .deb dans les releases Hugo :
https://github.com/gohugoio/hugo/releases
Ensuite :
wget https://github.com/gohugoio/hugo/releases/download/v0.82.1/hugo_extended_0.82.1_Linux-64bit.deb
sudo dpkg -i hugo_extended_0.82.1_Linux-64bit.deb
si erreurs de dépendances :
sudo apt-get install -f
Créer un socle de site
mkdir MONSITE
cd MONSITE
hugo new site .
Choisir et télécharger un thème : Hugo Themes
J’utilise hugo-clarity qui est très complet et fonctionne bien sur mobile :
cd MONSITE/
git submodule add https://github.com/chipzoller/hugo-clarity.git themes/hugo-clarity
Pour créer une page de test et vérifier que ça marche :
hugo new post/testpage.md
hugo server -D
Ouvrir : http://localhost:1313/
Note : Le thème hugo-clarity demande pas mal de conf. Plutôt que partir de zéro j’ai suivi le conseil que donne sa doc d’install et déployé le site exemple, que j’ai ensuite modifié :
cd MONSITE
cp -R themes/hugo-clarity/exampleSite/* .
hugo server -D
Github
Créer le dépôt
- Créer un compte Github “MONLOGINGITHUB” si ce n’est pas fait ;
- Créer un dépôt ("New repository") public qui contiendra nos pages.
Astuce Github :
Par défaut les dépôts sont exposés dans https://MONLOGINGITHUB.github.io/NOMDUDEPOT/.
Mais si vous nommez votre dépôt “MONLOGINGITHUB.github.io”, il sera accessible à la racine, dans https://MONLOGINGITHUB.github.io/.
Si on le souhaite, cela permet d’avoir plusieurs dépôts “projet” dans les sous-repertoires et une “page perso” à la racine :
Dépots Sites correspondants
------ --------------------
dayofthetentacle.github.io https//dayofthetentacle.github.io/
├── ifeel ├── https//dayofthetentacle.github.io/ifeel/
├── likeicould ├── https//dayofthetentacle.github.io/likeicould/
├── takeovertheworld ├── https//dayofthetentacle.github.io/takeovertheworld/
Si vous créez un compte Github uniquement pour héberger votre site, vous pouvez donc vous contenter du dépôt MONLOGINGITHUB.github.io.
Premier commit pour pouvoir activer Github Pages
Mettons notre site Hugo sur le dépôt MONSITE :
cd MONSITE
echo "# MONSITE" >> README.md
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/MONLOGINGITHUB/MONSITE.git
git branch -M main
git push -u origin main
Aller dans Settings > Pages et activer Pages avec comme source :
[Branch : gh-pages] [/root]
Générer le html statique directement côté Github
Note : Cette technique et le script ci-dessous sont repris de la doc Hugo : hosting on github.
On pourrait générer le html statique et le pousser sur Github, mais on peut aussi le faire faire par Github :
En ajoutant un script d’action à nos sources, à chaque git push on va lui faire :
- Exécuter un Hugo pour générer le html ;
- Ecrire le répertoire public/ généré dans une branche dédiée gh-branche que viendra lire Github Pages.
Créer le fichier de conf :
cd MONSITE
mkdir -p .github/workflows/
touch .github/workflows/hugo.yml
2 - Y mettre la conf (j’ai activé l’option “extended = true” par rapport au modèle, pour les besoins du thème Clarity) :
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages
on:
# Runs on pushes targeting the default branch
push:
branches:
- main
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
# Default to bash
defaults:
run:
shell: bash
jobs:
# Build job
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.115.4
steps:
- name: Install Hugo CLI
run: |
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Install Dart Sass
run: sudo snap install dart-sass
- name: Checkout
uses: actions/checkout@v3
with:
submodules: recursive
fetch-depth: 0
- name: Setup Pages
id: pages
uses: actions/configure-pages@v3
- name: Install Node.js dependencies
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
- name: Build with Hugo
env:
# For maximum backward compatibility with Hugo modules
HUGO_ENVIRONMENT: production
HUGO_ENV: production
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./public
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
On envoie tout sur Github et normalement ça marche
cd MONSITE
git add .
git commit -a -m "init"
git push
Dans l’onglet “Action” du dépôt on voit le traitement se dérouler (et éventuellement planter si on a fait des bêtises). La branche gh-pages a dû être créée.
Aller sur le site Github Pages résultant : MONLOGINGITHUB.github.io/MONSITE
En théorie tout y est.
Liens utiles
Docs sur Hugo sur github :
3 manières possibles d’organiser ses contenus Hugo : discourse.gohugo.io - content-organization-best-practice (j’ai opté pour l’organisation B : Un répertoire par publication contenant le .md et les pièces jointes. Cela évite les fausses manips, et sera plus pratique si un jour il y en a beaucoup)
Références Markdown :