Ce magnifique blog que vous tenez entre les mains à été généré à partir de fichiers Markdown, et mis en ligne automatiquement avec l'aide de GitLab et GitLab-ci. Nous allons voir dans une série d'article la mise en place de ce blog et l'automatisation de sa mise en ligne. Commençons dès aujourd'hui par la génération du site.

Un site statique

Qu'est-ce qu'un site statique

Un site statique est constitué uniquement de fichiers HTML, CSS et Javascript. Il s'oppose au site dynamique qui lui est composé d'une partie serveur, le backend. Celui ci permet de générer les pages HTML en fonction de la requête de l'utilisateur·trice.

L'avantage du site statique est qu'il est très facile à mettre en place car il demande peu de dépendances. Il y a juste besoin d'un serveur web pour servir les fichiers. Le site sera également très rapide car il n'y a pas de calcul côté serveur afin de générer les pages.

L'inconvénient est que sans partie serveur, nous ne pouvons pas avoir de contenu dynamique comme des comptes utilisateurs ou des commentaires.

mais, mais, je vois une zone commentaire à la fin de l'article !

En effet, cette zone commentaire est gérée par un service externe (mais auto-hébergé !), ce sera le sujet d'un prochain article.

Les générateurs de sites statiques

Pour éviter d'écrire du code HTML on va utiliser un générateur de site statique. C'est un programme qui va générer le code HTML du site à partir de fichiers de configuration et de fichiers de contenu.

La configuration va permettre de décrire la forme du site tandis que les fichiers de contenu vont inclure le texte des articles.

Le contenu est écrit en Markdown, un format facile à lire et à écrire qui sera converti en HTML par le générateur.

Il existe de nombreux générateurs de site statique, Jekyll, Hugo, Pelican … Nous allons ici utiliser Pelican car il est écrit en Python et que je maîtrise bien ce langage. Je pourrais plus facilement modifier des choses et faire de la configuration avancée si besoin.

Pelican

Installation avec Poetry

Pour l'installation, nous allons utiliser un environnement virtuel Python dans lequel nous installerons Poetry. Ensuite, nous ajouterons Pelican dans l'environnement virtuel avec Poetry.

python -m venv venv
pip install poetry
poetry init
poetry add "pelican[markdown]"

Maintenant que Pelican est installé, lançons le script quickstart pour générer une configuration par défaut.

pelican-quickstart

Une fois les fichiers édités, nous pouvons démarrer un serveur de développement avec make devserver. Le blog sera accessible à localhost:8000.

Configuration du thème

Pelican permet d'utiliser des thèmes afin de personnaliser un peu le style du blog. Après quelques recherches, je suis tombé sur le thème Papyrus qui propose un mode sombre et une fonction de recherche. Les instructions d'installation sont disponible sur le README.md du projet.

J'ai apporté les modifications suivantes au thème :

• l'ajout d'un fichier CSS pygment.css pour la coloration syntaxique des blocs de code. Ce fichier a été généré avec la commande :

pygmentize -S default -f html -a .highlight > pygment.css

• le téléchargement des ressources externes (CSS, Javascript) en local ;

• l'ajout de la zone commentaires.

Écriture du premier article

Les articles sont à écrire au format Markdown et à placer dans le répertoire content. L'article doit comporter un header qui sera interprété par Pelican pour générer les métadonnées du blog.

Title: Mon premier article
Date: 2010-12-03 10:20
Category: Test
Tags: article, test
Summary: Résumé de mon premier article

# Premier article

Ceci est mon premier article !

Afin de faciliter la création d'un nouvel article, j'ai ajouté une règle dans le Makefile. Celle ci va générer un fichier avec la date du jour et un header prérempli.

make article slug=un-nouvel-article
# 2022-12-11_un-nouvel-article.md

Conversion en HTML

Une fois notre premier article écrit, nous allons pouvoir générer le HTML. Pour cela, la commande make publish va se charger d'appeler la commande pelican avec les bons arguments.

make publish

Notre blog statique en HTML a été généré dans le répertoire output. Pour le consulter, nous pouvons ouvrir le fichier index.html dans notre navigateur préféré.

Et pour la suite

Maintenant que nous avons mis en place la génération de notre blog avec Pelican, il va falloir publier ces fichiers sur un serveur web. Nous verrons cela dans le prochain article de cette série.