Migrer vers un CMS

Jusqu’à la rédaction de cet article en anglais, chacune des pages de ce blog étaient assemblée à partir d’HTML et CSS brut, à la sueur de mon front. J’adore travailler directement en HTML et CSS. C’est presque thérapeutique. Une espèce de retour aux sources.

Mais malheureusement, l’argent que j’économise en évitant les visites chez mon psychiatre, je le dépense en paracétamol pour traiter les migraines terribles causées par les efforts nécessaires pour conserver les différentes pages du site dans un état cohérent.

J’ai donc décidé d’utiliser un CMS. Cela me permettra de réutiliser des parties du HTML que j’écris, me permettra d’utiliser du Markdown directement sans le convertir au préalable en HTML et simplifiera la gestion de la taxonomie des articles (les tags et les catégories).

Par contre, je ne veux pas utiliser le premier CMS venu. Je ne suis pas satisfait par WordPress ou même Drupal. J’ai testé de nombreux CMS, dans le cadre de mon travail, ainsi qu’à la maison dans le cadre de ma veille permanente. J’ai été déçu, comme c’est mon habitude, à la fois par la complexité inhérente à ces outils et la lourdeur engendrée par leur socle très fourni.

Parmi ces innombrables aspirateurs à RAM et autres outils dont l’interface utilisateur est un véritable labyrinthe, j’ai trouvé une pépite qui m’a redonné espoir : Hugo.

Note : Pour être tout-à-fait honnête, il existe de nombreuses alternatives à Hugo, toutes aussi performantes, la plupart portant le nom de « générateurs de sites statiques ». Gatsby, Next.js, Vuepress et autres outils du même type fonctionnent parfaitement bien. Personnellement, je préfère Hugo. Vous pouvez trouver de nombreux autres générateurs de sites statiques sur StaticGen.

Hugo est autoproclamé le « Framework le plus rapide pour construire des sites internet ». Quand je lis ce genre de déclaration, je deviens sceptique. Quand quelque chose semble être trop beau pour être vrai, c’est généralement le cas.

Je me suis donc résolu à tester si ces déclarations étaient vraies, ou juste le fruit de l’égo des mainteneurs de Hugo (sans vouloir les offenser). Mais si l’on prend en compte le fait que Hugo est développé en Go, ça promet des performances correctes.

Utiliser Hugo

Je vais vous épargner les étapes de l’installation de Hugo. Mais voici le lien vers le guide de démarrage si vous souhaitez tenter l’installation du CMS de votre côté.

Cet article décrit mon retour d’expérience à la suite de la migration du site en HTML brut vers Hugo.

Créer un nouveau site

La création d’un site avec hugo est assez simple. hugo créé l’arborescence de fichiers dont vous aurez besoin pour votre site internet, et un fichier config.yaml d’exemple. La commande suivante vous permet de créer un nouveau site.

hugo new site -f yaml my-site

Le paramètre -f yaml est optionnel. C’est juste que je préfère lire et écrire des fichiers YAML que TOML si j’ai le choix.

Une fois la commande exécutée, on se retrouve avec l’arborescence suivante :

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Vous pouvez trouver ici la description de chaque dossier. Pour l’instant, concentrons-nous sur le fichier config.yaml. Il contient la configuration de notre site internet.

Modifier le fichier config.yaml

Ce fichier config.yaml est la colonne vertébrale du site géré par hugo. Par défaut, il contient uniquement les lignes suivantes :

baseURL: http://example.org/
languageCode: en-us
title: My New Hugo Site

Les trois options ci-dessus s’expliquent d’elles-mêmes. Vous pouvez trouver la liste complète des options supportées par le fichier de configuration ici.

Une option de configuration essentielle pour ce blog, que vous ne trouverez pas en suivant ce lien est l’option pygmentsUseClasses: true. Cette option permet d’utiliser un fichier CSS personnalisé pour la colorisation syntaxique intégrée à hugo. (Le thème par défaut est Monokai. Donc si ça vous va, vous n’avez pas besoin de vous compliquer la vie à écrire du CSS en plus comme je l’ai fait)

Nous verrons comment construire le CSS pour la colorisation syntaxique un peu plus tard, et une fois encore, hugo va nous apporter un franc coup de main. Mais pour l’instant, continuez votre lecture.

Le serveur de développement avec rechargement à chaud

Une fonctionnalité que j’apprécie beaucoup avec hugo, c’est son serveur de développement intégré. Il est d’une rapidité fulgurante. En fait, il est capable de reconstruire le site et toutes ses pages en moins de 100ms.

Le serveur de développement compile votre contenu puis recharge la page en moins de temps qu’il vous faut pour cligner les yeux et louper le changement. J’ai été très impressionné la première fois que j’ai vu ça. J’étais encore en train de bidouiller webpack et d’autres task runners et builders, et l’expérience était tout autre.

hugo ne m’a pas déçu depuis cette première expérience. Je dois encore trouver comment utiliser le serveur de développement derrière un reverse proxy. J’utilise traefik comme load-balancer local vers tous mes projets. (J’aime conserver une machine propre, et j’utilise docker pour encapsuler mes différents environnements de développement et m’aider à rester ordonné.)

Je suis sûr que je trouverai au final, et quand ça sera le cas, je vous en parlerai. Dans tous les cas, ça ne m’empêche pas d’utiliser hugo, puisque c’est un projet en Go, et qu’il dispose d’exécutables pour toutes les plateformes, et l’installation est ultra simple (du genre copier-coller un fichier).

Archetypes

hugo dispose d’un autre point fort avec les archetypes. Les archetypes sont tout simplement des configurations par défaut pour votre contenu. hugo lit votre archetype (dans lequel vous pouvez même ajouter de la logique), puis génère un nouveau fichier de contenu prêt à utiliser. Super pratique.

Voici le genre de choses que l’on peut faire :

date: { { .Date } }
draft: true
resources:
  - name: picture
    src: picture.jpg
tags:
title: { { replace .Name "-" " " | title } }

Je déteste faire des tâches répétitives. Donc une nouvelle fois, hugo s’adapte à mes préférences.

Créer un thème personnalisé

Créer un thème personnalisé est tout aussi simple que de créer un site. hugo met à disposition une autre commande pour vous aider à créer la structure d’un nouveau thème.

hugo new theme my-theme

Et c’est tout !

Cela va créer un fichier config.toml, avec le contenu suivant par défaut :

# theme.toml template for a Hugo theme
# See https://github.com/gohugoio/hugoThemes#themetoml for an example

name = "Temp Theme"
license = "MIT"
licenselink = "https://github.com/yourname/yourtheme/blob/master/LICENSE"
description = ""
homepage = "http://example.com/"
tags = []
features = []
min_version = "0.41.0"

[author]
  name = ""
  homepage = ""

# If porting an existing theme
[original]
  name = ""
  homepage = ""
  repo = ""

Rien de tout ceci n’est sorcier, mais hugo simplifie la quantité de code que vous devez écrire, et je l’aime déjà pour ça.

hugo génère également trois dossiers. Vous devriez les reconnaître.

.
├── archetypes
├── theme.toml
├── layouts
└── static

Un thème est tout simplement certains de vos fichiers déplacés vers un dossier différents, que vous pouvez redistribuer s’ils sont accompagnés d’un fichier manifest. Super ! C’est simple, efficace et ne me demande pas d’apprendre une nouvelle structure de fichiers. Je trouve ça à la fois intelligent et bienveillant envers ceux qui utiliseront le logiciel.

Vous voyez, mesdames et messieurs, c’est comme ça que l’on écrit des logiciels de qualité : on se met à la place des utilisateurs et on s’efforce de leur faire gagner le plus de temps possible. Dit plus simplement, si votre logiciel ne me fait pas gagner de temps, je préfère continuer à utiliser un stylo et du papier.

Créer un shortcode personnalisé

hugo est dotés de shorcodes, comme d’autres CMS. Les shortcodes sont des petits modèles de contenu configurable que vous pouvez utiliser directement dans vos fichiers.

On peut voir sur plusieurs pages de ce blog des images suivies d’une légende. Ce genre de contenu n’existe pas en Markdown natif, il faudrait que j’écrive du HTML dans chaque page, mais avec un shortcode comme celui-ci :

{{< figure src="./roues.jpg" alt="Vieilles roues en bois"
    caption="“Quel est le problème avec ces roues ?” _— Nikola Tesla (ou pas)_" >}}

J’avais besoin de personnaliser les blocs de citations, donc j’ai créé mon propre shortcode. Créer un nouveau shortcode est facile. Il suffit de créer un fichier HTML dans le répertoire layouts/shortcodes de votre thème ou de votre site.

J’ai appelé le mien callout.html, et voici son contenu :

<blockquote>
    <p{{ with (.Get "type") }} class="{{ . }}"{{ end }}>
        {{ .Inner | markdownify }}
    </p>
</blockquote>

Et voici comment s’en servir dans les fichiers de contenu :

{{< callout type="info" >}}
**_Modification :_** _15 avril 2020 –_ Bon, je viens juste d’ajouter la
colorisation syntaxique et la numérotation des lignes comme effet de bord de la
migration du site vers Hugo. Youpi !
{{< /callout >}}

Je trouve cette fonctionnalité élégante et simple. hugo continue à gagner des points.

Ajouter un thème pour la colorisation syntaxique

Enfin, je voudrais que l’on parle de la colorisation syntaxique. hugo embarque chroma, une bibliothèque de colorisation syntaxique en Go inspirée par Pygments.

Grâce à chroma, hugo vous permet de coloriser le code source inclus dans vos pages. Le thème utilisé par défaut est Monokai, et bien que je possède une license de Monokai Pro, et que je l’utilise au quotidien, le thème me semblait dénoter avec le reste du site.

Du coup j’ai choisi de créer un thème personnalisé pour la colorisation syntaxique, en restant aussi simple que possible.

hugo peut générer la structure du code CSS pour vous, depuis l’un des thèmes disponible pour chroma, avec la commande suivante :

hugo gen chromastyles --style=dracula > syntax.css

Il suffit de changer quelques couleurs dans le CSS généré et c’est fini. C’est ce que j’ai fait pour le thème pour la colorisation syntaxique pour ce site.

Essayez d’abord, accordez votre confiance ensuite

J’ai tendance à ne pas facilement faire confiance aux nouveaux outils que je découvre. Pourtant, je me considère malgré tout comme un “early adopter”. C’est une façon de contrebalancer mon envie d’utiliser de nouveaux jouets avec mon besoin d’utiliser mon temps de façon efficace (en gros, d’éviter de débugguer du code en beta).

hugo est agréable à utiliser. La version anglaise de cet article était le premier à utiliser hugo. Cela devrait me permettre de me concentrer sur le contenu plutôt que d’écrire du HTML, même si c’est une de mes passions secrètes.

Quoi que vous fassiez, commencez toujours par tester vos outils, en profondeur. Une fois que vous avez déterminé avec certitude que vous pouvez travailler confortablement en leur compagnie, vous pouvez commencer à les bidouiller, les optimiser et même éventuellement corriger des bugs. Si vous trouvez un bug et le corrigez, faite une PR, contribuez à votre outil. Ça peut tout simplement être quelques lignes de documentation ou une fonctionnalité dont vous aviez besoin.

C’est bon pour votre moral, ça aidera les autres utilisateurs du même outil et ça contribuera à développer votre expérience en tant que développeur.

Si vous utilisez des outils particuliers que vous adorez, ou que vous en développez un vous-même, dites le moi. Vous pouvez m’en parler sur Twitter.