Il y a un an, on pouvait lire dans le Fake’IT :

Retrouvez tous les meilleurs articles du Goraf’IT en ligne sur le site https://tasvraimentcruquonavaitfaitunsite.onapasdethunes.org

Un site web entièrement personnalisable, gratuit et rapide à mettre en œuvre, ça vous tente ?

Voici un guide pas à pas qui aurait pu servir à la Post’Liste.

Préambule

Choix techniques

Pour ce guide, nous allons utiliser les même outils que pour le site d'Ensilibre :

Hugo pour la génération du site à partir de sources en Markdown
Le service Gitlab Pages de l’Ensimag pour l’hébergement

Le choix de ces deux composants est indépendant.

Nous supposerons que vous avez configuré une clé SSH pour pouvoir pousser vers gitlab.ensimag.fr.

Choix de l’exemple

Le site d’exemple est celui du Goraf’IT. Le site fini est ici et les sources sur l'instance Gitlab de l’Ensimag.

Étape 0 : Installer les outils de développement

Seulement deux dépendances :

Git (supposons que vous l’avez déjà)
Hugo

sudo pacman -Syu --needed hugo # Sur BubuOS, Manjaro ou Arch
snap install hugo --channel=extended # Si vous avez snapd sur votre système

Si vous êtes dans un autre cas, consultez le guide officiel.

Étape 1 : Créer le squelette du site

hugo new site gorafit
cd gorafit

Étape 2 : Initialisation du dépôt Git

git init
echo "/public" >> .gitignore
git add .
git commit -m "Hugo skeleton"

Étape 3 : Choisir et installer un thème

Il existe beaucoup de thèmes prêts à l’emploi pour Hugo. Une liste est disponible ici. Pour cet exemple nous utiliserons tranquilpeak.

git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/tranquilpeak
git commit -m "Add theme"

Étape 4 : Configuration initiale du site

Dans votre éditeur de texte favori, ouvrez le fichier config.toml et modifiez-le à votre convenance. Les thèmes Hugo fournissent en général un config.toml commenté dans le dossier exampleSite. Par exemple pour notre thème il est ici.

Il est aussi possible de personnaliser le thème plus en profondeur. Pour chaque fichier fourni par le thème, il est possible de l'override en créant un fichier qui respecte la même hiérarchie. Dans notre exemple, le pied de page proposé “Tous droits réservés” ne nous convenait pas. Il était défini dans themes/tranquilpeak/layouts/partials/footer.html, donc on peut le redéfinir dans layouts/partials/footer.html.

Pour vérifier vos modifications, vous pouvez lancer Hugo en mode serveur avec la commande hugo server. À chaque changement le navigateur rechargera automatiquement la page.

Quand vous avez fini :

git add .
git commit -m "Configure theme"

Étape 5 : Préparer la publication avec Gitlab Pages

Gitlab a besoin d’un fichier .gitlab-ci.yml pour savoir quoi faire de votre code. Mettez-y ce contenu :

image: registry.gitlab.com/pages/hugo:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

before_script:
  - apk add --update --no-cache git

test:
  script:
    - hugo
  except:
    - master

pages:
  script:
    - hugo
  artifacts:
    paths:
      - public
  only:
    - master

N’oubliez pas de valider :

git add .gitlab-ci.yml
git commit -m "Gitlab Pages config"

Étape 6 : Créer le dépôt sur Gitlab et pousser

Sur gitlab.ensimag.fr, créez un groupe gorafit. Dans ce groupe, créez le dépôt vide gorafit.pages.ensimag.fr.

Allez dans Paramètres → Intégration et livraison continue → Exécuteurs et activez les exécuteurs partagés.

Puis poussez :

git remote add origin git@gitlab.ensimag.fr:gorafit/gorafit.pages.ensimag.fr.git
git push --set-upstream origin master

Gitlab va se charger de générer le site avec Hugo puis le rendre disponible sur gorafit.pages.ensimag.fr.

Étapes suivantes : Ajouter des pages

Avec Hugo 1 page = 1 fichier. Par défaut les pages peuvent être rédigées en Markdown, ReStructured Text ou même le mode Org d’Emacs.

Créons un nouveau post de blog en markdown :

hugo new posts/stage-dassault.md

Modifiez le nouveau fichier content/posts/stage-dassault.md à votre convenance (exemple). La section en début de fichier est le front matter et permet de définir les métadonnées de la page, notamment le titre, les catégories et les tags.