Commit 0ce46605 authored by Nicolas Guichard's avatar Nicolas Guichard 😿

Tuto Hugo

parent c3c4ea26
Pipeline #8503 passed with stage
in 25 seconds
+++
title = "Tutoriel site statique"
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 utilisez BubuOS et 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
* Hugo
```sh
sudo pacman -Syu --needed git hugo
```
# É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`.
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`.
# É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 Emacs Org-mode.
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. 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