Commit f12e961b authored by Nicolas Guichard's avatar Nicolas Guichard 😿 Committed by Jules De Sartiges

Tuto Hugo

parent c3c4ea26
+++
title = "Tutoriel site statique avec Hugo"
date = "2020-01-25"
author = "Nicolas Guichard"
tags = ["tutoriel", "hugo", "gitlab"]
+++
Il y a un an, on pouvait lire dans le [Fake'IT](/FakeIT.pdf) :
> Retrouvez tous les meilleurs articles du Goraf’IT en ligne sur le site
http://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.
<!--more-->
# Préambule
## Choix techniques
Pour ce guide, nous allons utiliser les même outils que pour le site
d'[Ensilibre](https://ensilib.re) :
* 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](http://gorafit.pages.ensimag.fr) et les sources sur
l'[instance Gitlab de l'Ensimag](https://gitlab.ensimag.fr/gorafit/gorafit.pages.ensimag.fr).
# Étape 0 : Installer les outils de développement
Seulement deux dépendances :
* Git (supposons que vous l'avez déjà)
* Hugo
```sh
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](https://gohugo.io/getting-started/installing/).
# Étape 1 : Créer le squelette du site
```bash
hugo new site gorafit
cd gorafit
```
# Étape 2 : Initialisation du dépôt Git
```bash
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](https://themes.gohugo.io). Pour cet exemple nous utiliserons
[tranquilpeak](https://themes.gohugo.io/hugo-tranquilpeak-theme/).
```bash
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](https://github.com/kakawait/hugo-tranquilpeak-theme/blob/master/exampleSite/config.toml).
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`](https://github.com/kakawait/hugo-tranquilpeak-theme/blob/master/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 :
```bash
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 :
```yml
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 :
```bash
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](https://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 :
```bash
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`](http://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 :
```bash
hugo new posts/stage-dassault.md
```
Modifiez le nouveau fichier `content/posts/stage-dassault.md` à votre
convenance ([exemple](https://gitlab.ensimag.fr/gorafit/gorafit.pages.ensimag.fr/blob/master/content/post/stage-dassault.md)). La section en début de fichier est le
[front matter](https://gohugo.io/content-management/front-matter) et permet de
définir les métadonnées de la page, notamment le titre, les catégories et les
tags.
Quand vous avez fini :
```bash
git add content/post/stage-dassault.md
git commit -m "[New post] Stage Dassault"
git push
```
# Pour aller plus loin
Il serait compliqué de faire une liste exhaustive des capacités d'Hugo ici. Pour
plus d'informations, consultez la [documentation officielle](https://gohugo.io/documentation/).
Vous serez peut-être intéressés en particulier par sa gestion de
l'[internationalisation](https://gohugo.io/content-management/multilingual/),
de plusieurs [types de contenu](https://gohugo.io/content-management/types/)
ainsi que son support du format [RSS](https://gohugo.io/templates/rss).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment