Créer un blog grâce au framework Go Hugo

4 Décembre 2020 à 13:00 Web

Je ne publierai plus rien sur ce blog. Un nouveau blog existe maintenant. Il se nomme Hardly Smart.

Vous pourrez y retrouver des astuces plus larges sur l'informatique ainsi que mes anciens billets de blog.

Je vous souhaite une bonne lecture sur Hardly Smart.


Hugo est un générateur de site statique comme Jekyll (développé en Ruby). C’est-à-dire qu’il n’a pas besoin de base de données ou autre pour fonctionner.

Les pages sont donc générées lors de la création ou à la modification d’un contenu. L’avantage, est qu’il fonctionne sans dépendances. Pas comme Ruby, Python ou PHP.

Avant-propos

Site utilisant Hugo

Hugo est assez répandu et utilisé pour sa mise en place rapide, sa rapidité d’exécution et sa souplesse. Entre autres il y a comme site :

  • Github Pages
  • Amazon S3
  • Azure
  • Let’s Encrypt

Avantages

L’un des avantages c’est sa rapidité pour le build de vos pages (< 1ms). L’autre c’est qu’il est multi-platforme et possède un système de live reload. C’est-à-dire que lors de la modification d’un contenu, il va détecter ce qui est modifié et rebuilder instantanément le contenu, même pour ceux qui auraient déjà la page en cours de lecture.

Création du blog

Installation

L’installation est très simple et rapide. La documentation est disponible à cette adresse : https://gohugo.io/getting-started/quick-start/. Les thèmes ou plugins s’installent via les submodules de git.

Pour cet exemple nous allons utiliser le thème bleak.

hugo new site blog
cd blog
git init
git submodule add https://github.com/Zenithar/hugo-theme-bleak.git themes/bleak
echo 'theme = "bleak"' >> config.toml
cp themes/bleak/archetypes/default.md archetypes/default.md
hugo server

Lors du lancement de notre serveur via la commande hugo server, il est possible de lui passer comme paramètre -D ou --buildDrafts. Cela permet de lui dire d’inclure les contenus qui sont marqués comme brouillon ou draft dans la compilation automatique.

Création d’un article

Pour créer un article, rien de bien compliqué :

hugo new posts/my-first-content.md
nano content/posts/my-first-content.md

Déploiement

Avoir un blog c’est bien mais l’héberger c’est encore mieux. Nous allons pour cela faire en sorte d’avoir un repository (public ou private) qui contiendra nos sources et un repository qui contiendra le blog compilé. L’avantage de stocker cela sur un repository Github est la possibilité de bénéficier gratuitement d’un hébergement et d’un nom de domaine (github_user.github.io).

Nous allons donc créer deux repositories, l’un nommé par exemple blog-go-src et l’autre github_user.github.iogithub_user correspond à votre nom d’utilisateur Github.

CircleCI

Pour déployer notre blog nous allons utiliser l’offre gratuite de CircleCI. CircleCI est un outil d’intégration continue qui permet de gérer divers jobs en fonction de plusieurs paramètres.

Vous allez par exemple pouvoir exécuter du code à la création d’un pull request (tests unitaires) et au merge de cette pull request faire en sorte de pousser votre code sur vos différents envionnements. C’est ce que nous allons justement faire mais sans la partie tests unitaires.

Nous allons d’abord commencer par nous créer un compte et dans la partie de gauche, cliquer sur Add projects et ajouter notre repository principal en cliquant sur Set Up Project. Une fois créé la CI va s’exécuter et bien sûr comme nous n’avons rien paramétré elle va être rouge et marquer build error.

Pour paramétrer CircleCI il faut créer un dossier .circleci à la racine de votre projet et créer un fichier config.yml. Et dans ce fichier vous allez mettre ceci :

version: 2.1

commands:
    checkout-alpine:
        description: Install alpine requirements for checkout
        steps:
            - run:
                  name: "Install alpine requirements for checkout"
                  command: apk add git openssh-client curl make
            - checkout
            - run:
                  name: "Init submodules"
                  command: |
                      git submodule init;
                      git submodule update;

    hugo-install:
        description: Install Hugo for compile blog
        steps:
            - run:
                  name: "Download Hugo"
                  command: |
                      if [ ! -f /usr/local/bin/hugo ];then
                          curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-64bit.tar.gz | tar -xz;
                          mv hugo /usr/local/bin/hugo;
                      fi

    restore-hugo-install-cache:
        description: "Restore Hugo install"
        steps:
            - restore_cache:
                key: hugo-install-v${HUGO_VERSION}

    store-hugo-install-cache:
        description: "Store Hugo install in CircleCI cache"
        steps:
            - checkout-alpine
            - restore-hugo-install-cache
            - hugo-install
            - save_cache:
                  key: hugo-install-v0.1
                  paths:
                      - /usr/local/bin
            - persist_to_workspace:
                  root: /
                  paths:
                      - usr/local/bin

    hugo-compile:
        description: Compile & deploy blog
        steps:
            - add_ssh_keys:
                  fingerprints:
                      - "YOUR_FINGER_PRINT"
            - run:
                  name: "Compile & deploy blog"
                  command: ./deploy.sh

executors:
    hugo:
        docker:
            - image: alpine:latest
        working_directory: ~/repository

jobs:
    hugo:
        executor: hugo
        steps:
            - store-hugo-install-cache
            - hugo-compile

workflows:
    version: 2.1
    Compile & deploy:
        jobs:
            - hugo:
                  filters:
                      branches:
                          only: master

La syntaxe est assez simple à comprendre vous allez voir :

  • commands: correspond à un lot de commandes bash ou natives à CircleCI pouvant être exécutées dans un job. Dans ces commandes, il y a notamment une commande permettant de stocker et récupérer le binaire hugo. Cela permet de gagner du temps dans la CI et ainsi ne pas être obligé de télécharger à chaque pull request le nouveau binaire
  • executors: correspond à un lot d’images docker qui vont être utilisées dans vos jobs
  • jobs: correspond aux tâches qui vont être exécutées dans vos workflows avec en paramètre les executors et les commands associées
  • workflows: Comment votre CI doit fonctionner. C’est notamment ici que vous allez pouvoir lancer en parallèle vos tests unitaires et si ceux-ci ont bien fonctionné lancer votre déploiement

Dans la partie workflows vous constaterez que nous avons un filtre qui n’est que la branche master. Il permet de faire en sorte que CircleCI ne lance le job que si le code va sur la branche master.

Comme je l’ai dit plus haut nous allons devoir pousser notre code sur un autre repository. Le souci c’est que CircleCI n’a pas les accès pour le faire. Nous allons donc devoir créer une clé SSH et l’utiliser dans CircleCI.

ssh-keygen -m PEM -t rsa -C "your_email@example.com"

Une fois cette clé créée, vous allez devoir l’ajouter à votre projet en allant dans les paramètres de votre projet puis dans SSH Permissions. Quand celle-ci sera créée, vous aurez une fingerprint que vous renseignerez dans la commande où vous avez le git push. Dans notre cas ça sera dans la commande hugo-compile.

Script de déploiement

Afin de ne pas voir une commande trop longue à écrire dans le fichier de configuration CircleCI, il est préférable d’externaliser cela dans un script bash.

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

git config --global user.email "github_email"
git config --global user.name "github_user"

# Add destination repository
git submodule add -b master -f git@github.com:github_user/github_repository public

# Build the project.
hugo -t bleak

# Go to public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
    msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

Votre blog peut maintenant se compiler tout seul à chaque merge d’un article.

Articles liés

Les commentaires ont été désactivés.

2 commentaires

Tycal 25 Février 2023 à 14:51

bjr
merci pour votre tuto que j'essaie de reproduire en finalité j'ai ce méssage.Error: module "bleak" not found; either add it as a Hugo Module or store it in "/Users/tycal/web/themes".: module does not exist

merc si c'est possible pour vos lumiéres
tycal

BaBeuloula 26 Février 2023 à 09:49

Salut Tycal, tu as bien installé le thème ?
Après je t'encourage à prendre un autre thème ou à regarder la documentation qui entre mon article de 2020 et maintenant a beaucoup évoluée.