Faire un site statique avec Hugo et l'héberger sur Github

Ce document décrit une procédure pour créer un site statique avec Hugo (écrit avec le langage Go) et l’héberger sur Github… sur l’exemple de ce site : https://alenorcy.github.io

Par la suite, le contenu du site pourra être rédigé en Markdown avec par exemple VSCodium ou bien neovim + lunarvim!

Pré-requis : avoir déjà créé un compte Github !

Sommaire :

Création d’un repository Github
Création du site en local (sur Ubuntu)
Création du dépôt Git local
Mise en place d’un thème pour Hugo
Premier test
Première synchronisation distante
Configuration finale sur le repositoy Github

Création du repository Github#

Depuis votre profil, cliquez sur l’onglet sur Repositories puis sur le bouton New :

New repository Github

Saisissez un nom avec ce format [compte].github.io (attention ce format précis est indispensable ! Il faut absolument précéder .github.io de son compte. Mon compte Github est alenorcy) :

Repository name

Github vous indique ensuite quelques conseils d’utilisation :

Git advice

Création du site en local (sur Ubuntu)#

Installation de Hugo (sur Ubuntu 20.04) :

snap install hugo --channel=extended

Création du site avec Hugo :

hugo new site alenorcy.github.io

Création du dépôt Git local#

On crée le dépôt local :

cd alenorcy.github.io
git init

Mise en place d’un thème pour Hugo#

On choisit le thème codex :

git submodule add https://github.com/jakewies/hugo-theme-codex.git themes/hugo-theme-codex
cp themes/hugo-theme-codex/exampleSite/config.toml .

On modifie quelques lignes du fichier config.toml :

  • On commente la ligne themesDir = “../../”,
  • On modifie title, baseURL dans les paramètres globaux,
  • On modifie twitter et github dans les paramètres optionnels [params],

Premier test#

Lancement du site en local :

hugo server -D

En lançant l’URL http://localhost:1313/ dans son navigateur, on peut vérifier si le site statique est OK :

Hugo desktop screenshot

Première synchronisation distante#

On envoie les fichiers locaux vers la branche distante (main) :

git add .
git commit -m "premier commit"
git branch -M main
git remote add origin https://*******-mon_token-***********@github.com/alenorcy/alenorcy.github.io.git
git push -u origin main

Configuration finale sur le repositoy Github#

Dans Settings > Pages > Source, on positionne construction du site statique dans la branche distante “gh-pages” : gh-pages

On créé le fichier .github/workflows/gh-pages.yml suivant (depuis l’interface de Github dans la branche main) :

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

On le récupère en local :

git pull

Et c’est terminé :-)

On peut ensuite mettre à jour son site en local… et pousser les modifications sur Github :

git add .
git commit -m "mes modifications blabla"
git push -u origin main

Liens :

Bonne journée.