Le coin de Tropez

Transfert du blog Dotclear vers un site statique à base de pelican (Python)

Références :

Le tutoriel sur "Zeste de savoir" a été mon fil conducteur tout au long de la création du site.

J'utilise Ubuntu 18.04 comme système d'exploitation.

Installation de Pelican :

L'installation peut se faire globalement ou dans un environnement virtuel. En accord avec ce qui est proposé sur "Zeste de savoir", j'ai utilisé un environnement virtuel.

Au moment où j'écris ce tutoriel, Python 2.7 et Python 3 cohabitent encore souvent sur les systèmes d'exploitation. Dans la mesure du possible, il vaut mieux privilégier Python 3. De même, je préfère utiliser le module venv de Python 3 plutôt que Virtualenv.

Les commandes utilisées ci-après sont à exécuter dans un terminal.

Création de l'environnement virtuel :

python3 -m venv ~/projets/tropezblog/venv
cd ~/projets/tropezblog
source venv/bin/activate

Installation de pelican :

pip install pelican Markdown

Configuration initiale du site :

pelican-quickstart

Cette commande lance un script interactif qui va pré-remplir les fichiers de configuration (tout pourra être modifié par la suite dans le fichier pelicanconf.py). En dehors des données de personnalisation propres au site en création (nom, auteur), il suffit d'accepter la plupart des réponses par défaut. Il n'y a qu'à la question : Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) que j'ai répondu non.

Fonctionnement de pelican :

A ce stade de l'installation, pelican a créé les répertoires et fichiers suivants dans ~/projets/tropezblog/ :

content/
output/
pelicanconf.py
publishconf.py

En pratique, on écrit des fichiers au format markdown qui sont stockés dans le répertoire content et pelican se charge d'en faire des fichiers HTML qui sont enregistrés dans le répertoire output. C'est le contenu d'output qui doit être exporté vers votre hébergement web.

La commande pelican --help permet de voir toutes les options de Pelican.

pelicanconf.py est le fichier de configuration de pelican. C'est là qu'on peut compléter ou modifier ce qui a été enregistré par le script pelican-quickstart.
publishconf.py ne sert que si on a répondu oui à l'option "Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)".

Plus précisément, après avoir écrit et enregistrés les fichiers markdown avec notre éditeur de texte favori dans le répertoire content, on tape pelican et les fichiers HTML sont générés dans output.

Deux options de pelican sont très utiles et permettent d'économiser ses doigts et son clavier :

pelican -l : lance un serveur interne qui affiche le rendu du site sur http://localhost:8000
pelican -r : relance automatiquement pelican chaque fois qu'un fichier quel qu'il soit est modifié.

Donc pour résumer, lorsque je veux travailler sur mon site :

je lance un terminal
cd ~/projets/tropezblog/
source venv/bin/activate
pelican -l -r

je démarre un navigateur et je vais sur http://localhost:8000

je démarre mon éditeur de texte et je travaille sur les fichiers du site (articles, css, images, configuration,...)

je rafraîchi le navigateur pour voir le résultat

quand j'ai fini, je retourne dans le terminal
Ctrl C pour arrêter le serveur pelican
deactivate pour sortir de l'environnement virtuel.

Quand, tout est prêt, je copie le contenu d'output sur mon hébergement via ftp. Le cas échéant, on peut également utiliser git.

Import des données du blog Dotclear :

Installation des dépendances nécessaires à l'import des données de mon blog Dotclear :

pip install BeautifulSoup4 lxml
sudo apt install pandoc

J'ai également récupéré une sauvegarde de ma base de données Dotclear.

L'importation des données se fait via l'outil "pelican-import" (pour avoir une idée de ce que ce dernier sait faire, voir le site en référence 2) :

pelican-import --dotclear -o content -m markdown backupDotclear.txt

lire :

-m markdown : import des articles au format markdown
-o content : les fichiers markdown obtenus sont copiés dans le répertoire "content" de pelican.

Il n'est pas inutile de faire un peu de cosmétique dans les fichiers obtenus mais cela peut fonctionner sans.

Personnalisation du thème :

L'installation d'un thème se fait par l'outil pelican-themes. On peut voir les options disponibles en tapant :

pelican-themes -h (ou --help).
pelican-theme -l liste les thèmes installés
pelican-theme -i theme_path installe un thème
pelican-theme -r theme_name désinstalle un thème

Le site http://www.pelicanthemes.com/ présente les thèmes disponibles pour pelican. Ils sont récupérables sur Github : https://github.com/getpelican/pelican-themes.

J'ai essayé d'en trouver un proche de ce que je voulais obtenir afin de le modifier par la suite mais cela s'est avéré plus complexe que prévu, ces thèmes étant assez sophistiqués (javascript) et mes connaissances dans le domaine un peu trop limitées. Du coup, retour vers le thème de base proposé par "zeste de savoir" (cf. réf 1) plus facile à améliorer et avec l'avantage d'apprendre à créer un thème à partir de zéro.

Pelican utilise le moteur de template Jinja2.

Les templates se divisent en différentes pages HTML ayant chacune une fonction particulière.

A cela s'ajoute la possibilité de diviser une page en plusieurs "morceaux", pour éviter de réécrire les éléments qui se répètent. Concrètement cela se traduit par la création d'un squelette (base.html) servant de base à la création d'une page puis sa personnalisation en important des morceaux de page via la commande :

{% include 'chemin du morceau.html' %}

Par exemple, voici, arrivé là, ma page base.html :

base.html

Et ma page index.html :

index.html

Tout cela est très clairement expliqué sur zeste de savoir ou dans la documentation pélican (réf. 1 et 3).

Le thème utilise également des variables qui sont définies dans le fichier pelicanconf.py (emplacement des fichiers du thème par exemple).

Mon arborescence de pélican se complète donc d'un répertoire pour mon thème dont le contenu est :

Arborescence theme

Le répertoire "parts" (qu'on peut aussi appeler "includes") contient les morceaux html. Il n'est pas obligatoire de les mettre dans un répertoire spécifique mais ça ne coûte rien et cela facilite l'exploitation du site. Le mien contient, à ce stade, les fichiers :
articles-list.part.html,
footer.part.html,
header.part.html,
high-level-list.part.html
sidebar.part.html.

J'ai adopté un style avec une barre latérale. Celle-ci contient une liste de liens. Ces derniers sont définis sous forme de variables dans le fichier pelicanconf.py.

A ce stade, mon fichier pelicanconf.py ressemble à ça :

pelicanconf.py

Ajout d'un champs de recherche - les plugins

Pour inclure un champs de recherche dans ma barre latérale, j'ai utilisé le plugin Tipue Search. Au départ, je me suis appuyé sur les sites en références 5 et 6. J'ai eu un peu de mal à voir exactement ce qu'il fallait faire et c'est après avoir trouvé le site en référence 4 que j'ai pu obtenir un champs de recherche fonctionnel (même si le site est un peu ancien et certains liens ne fonctionnent plus). Au bilan, cela se traduit par :

installation de beautifulsoup4 (pip install BeautifulSoup4, déjà fait en ce qui me concerne pour l'import dotclear, voir ci-dessus);
téléchargement des fichiers de thème sur tipue.con (réf. 6). Après décompression de l'archive obtenue, j'en ai extrait le répertoire tipuesearch (qui contient les fichier css et js) et je l'ai copié dans le répertoire static de tropeztheme. Attention, le fichier tipuesearch_content.js est à supprimer, il sera créé automatiquement par le plugin dans le répertoire output;
téléchargement des fichiers du plugin tipue_search (tipue_search.py, __init__.py) sur github (réf. 5). J'ai copié ces fichiers dans un répertoire tipue_search lui même placé dans un répertoire plugins créé à la racine de l'arborescence pelican aux côtés de content, output et tropeztheme;
téléchargement du fichier normalize.css sur https://cdnjs.com/libraries/normalize et copie dans tropeztheme/static/css;
téléchargement du fichier jquery-3.5.0.min.js (version au moment où j'ai fait la manipulation) sur https://jquery.com/download/ et copie dans tropeztheme/static/js;
ajout dans l'en-tète du fichier base.html des lignes suivantes :
ajout dans le fichier pelicanconf.py des lignes suivantes :

PLUGIN_PATHS = ['plugins']
PLUGINS = ['tipue_search']
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'search']
création dans le répertoire /templates/parts d'un fichier search.part.html servant à afficher le champs de recherche. Le contenu que j'ai adopté mais qui pourrait bien sur être amélioré est :
affichage du champs de recherche dans la barre latérale en appelant le contenu de search.part.html dans le fichier sidebar.part.html via la commande :

{% include '/parts/search.part.html' %}
création dans le répertoire /templates d'un fichier search.html servant à afficher les résultats de recherche. Le mien contient :
un peu de cosmétique dans le fichier tipuesearch.css principalement pour adapter les couleurs et la taille du champs de recherche.

Et pour finir, un peu de responsive

Un dernier petit effort, améliorer l'affichage sur les smartphones. J'ai tatonné quelques temps et lu pas mal de documentation sur le web. J'ai fini par obtenir l'effet recherché même si ma solution n'est ni la plus propre ni la plus optimisée. Le but était de passer d'un affichage sous la forme :

Style normal

à un affichage :

Style responsive

Cela se traduit par :

création d'un fichier minStyle.css dérivé du fichier style.css dans lequel j'ai, pour l'essentiel, enlevé tout ce qui est float ou flex-box; joué sur quelques marges (margin et surtout padding); enlevé toutes les largeurs fixes;
modification de l'en-tête du fichier base.html en remplaçant l'appel du fichier style.css par :