tuto-hugo.md 5.55 KB
Newer Older
Nicolas Guichard's avatar
Nicolas Guichard committed
1
+++
2
title = "Tutoriel site statique avec Hugo"
Nicolas Guichard's avatar
Nicolas Guichard committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
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.

Nicolas Guichard's avatar
Nicolas Guichard committed
30 31
Nous supposerons que vous avez configuré une clé SSH pour pouvoir
pousser vers `gitlab.ensimag.fr`.
Nicolas Guichard's avatar
Nicolas Guichard committed
32 33 34 35 36 37 38 39 40 41

## 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 :
42
 * Git (supposons que vous l'avez déjà)
Nicolas Guichard's avatar
Nicolas Guichard committed
43 44 45
 * Hugo

```sh
46 47
sudo pacman -Syu --needed hugo # Sur BubuOS, Manjaro ou Arch
snap install hugo --channel=extended # Si vous avez snapd sur votre système
Nicolas Guichard's avatar
Nicolas Guichard committed
48 49
```

50 51
Si vous êtes dans un autre cas, consultez le [guide officiel](https://gohugo.io/getting-started/installing/).

Nicolas Guichard's avatar
Nicolas Guichard committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
# É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
Nicolas Guichard's avatar
Nicolas Guichard committed
152
[`gorafit.pages.ensimag.fr`](http://gorafit.pages.ensimag.fr/).
Nicolas Guichard's avatar
Nicolas Guichard committed
153 154 155 156

# Étapes suivantes : Ajouter des pages

Avec Hugo `1 page = 1 fichier`. Par défaut les pages peuvent être rédigées en
157
Markdown, ReStructured Text ou même le mode Org d'Emacs.
Nicolas Guichard's avatar
Nicolas Guichard committed
158 159 160 161 162 163 164

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
165
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
Nicolas Guichard's avatar
Nicolas Guichard committed
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
[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).