Markdown on Jean-Christophe Gay

Migration de Pelican vers Hugo

Sun, 20 Oct 2019 11:35:00 +0200

Retour sur la migration d’un blog construit avec Pelican pour un site statique généré avec Hugo.

Ça fait un moment que je n’ai pas posté ici. Pour le dépoussierage je reviens sur la migration du générateur de ce site.

J’utilisais Pelican depuis plusieurs années. Récemment j’ai réinstallé ma machine, j’avais bien entendu sauvegardé l’environnement virtuel qui me servait à générér mon site mais au moment de le restaurer je me suis dit que c’était le bon moment pour changer.

J’ai souvent eu des problèmes avec la gestion de mon environnement Python (pour tout dire ce n’est vraiment pas ma zone de confort, et je n’en touche que très rarement…), que ce soit à cause des chemins vers mes installations de Python ou bien à cause des mises à jour de Pelican et de ses dépendances. Du coup je surveille ce qui se passe un peu dans l’univers des générateurs de site et je suis resté bloqué sur Hugo et Gatsby.

Les deux semblent assez populaires et assez similaires en terme de fonctionalités. Comme je suis bien plus à l’aise avec Go qu’avec l’écosystème React le choix a été assez facile 😇.

Ce qui m’a encouragé à migrer est que pour utiliser Hugo il suffit d’utiliser un binaire tout en un. Pas besoin de gérer x dépendances 🚀. C’est donc plus simple de reproduire la génération de son site dans le temps.

Installation
#

Il a suffit de suivre le guide d’installation soit sur macOS un simple :

brew install hugo

Puis de générer la structure du site (dans le dossier existant) avec :

hugo new site jeanchristophegay.com

Theme
#

J’ai choisi Beautiful Hugo pour le moment.
L’installation a été rapide en suivant les simples étapes de la documentation.

Migrer les articles
#

Les articles sont déplacés dans le dossier content/posts pour respecter la structure d’Hugo.
Les images sont maintenant dans static/images pour ne pas devoir réécrire les URL.

Les articles sont déjà rédigés en Markdown, il faut donc s’occuper de convertir les métadonnés et les quelques balises spécifiques à Pelican.

Les métadonnées de Pelican ressemblaient à :

Title: De la couleur dans les logs
Date: 2013-05-04 18:22
Category: java
Tags: ansi console, grep console, jansi, log, log4j, log4j 2, logback
-Slug: de-la-couleur-dans-les-logs
-Author: Jean-Christophe Gay
-lang: fr
disqus_identifier: 213 http://jeanchristophegay.com/?p=213

Pour Hugo, il faut les transformer en :

---
title: "De la couleur dans les logs"
date: 2013-05-04T18:22:00+02:00
aliases:
 - /de-la-couleur-dans-les-logs/
slug: de-la-couleur-dans-les-logs
categories:
 - java
tags:
 - ansi console
 - grep console
 - jansi
 - log
 - log4j
 - log4j 2
 - logback
disqus_identifier: "213 http://jeanchristophegay.com/?p=213"
---

Toutes les options possibles sont listées dans la documentation.

L’attribut aliases est bien pratique pour conserver les anciennes URL générées par Pelican.

Pelican : https://jeanchristophegay.com/de-la-couleur-dans-les-logs/ Hugo : https://jeanchristophegay.com/posts/de-la-couleur-dans-les-logs/

La balises  qui permettait de délimiter le résumé d’un article est remplacé par .

Pour le moment j’ai perdu la table des matières, apparemment certains thèmes permettent d’en générer une mais je n’ai pas encore essayé.

Pour les articles disponibles en plusieurs langues, pas besoin de metadonnées, le suffixe dans le nom de fichier est suffisant.

Configuration
#

Site
#

La configuration se déroule dans un fichier config.toml à la place de pelicanconf.py et publishconf.py. On y retrouve un peu le même genre d’options que dans Pelican.

Pour exemple voici à quoi ressemble le mien à ce jour :

baseURL = "https://jeanchristophegay.com/"
languageCode = "fr-FR"

title = "Jean-Christophe Gay"
theme = "beautifulhugo"
disqusShortname = ""
googleAnalytics = ""

enableEmoji = true
enableGitInfo = true
enableRobotsTXT = true

DefaultContentLanguage = "fr"
[languages]
 [languages.fr]
 weight = 1
 [languages.en]
 weight = 2

[[menu.main]]
 name = "Home"
 url = "/"
 weight = 1

[[menu.main]]
 name = "Tags"
 url = "tags"
 weight = 3

[Params]
 subtitle = "Développeur"
 mainSections = ["post","posts"]
 logo = "https://www.gravatar.com/avatar/5cee6a7b8d17e4a0f367a5f0e237c694?s=200"
 dateFormat = "2 Jan 2006"
 rss = true
 comments = true
 readingTime = true
 wordCount = false
 socialShare = true
 delayDisqus = false
 showRelatedPosts = true
 
[Author]
 name = "Jean-Christophe Gay"
 website = "jeanchristophegay.com"
 email = "contact@jeanchristophegay.com"
 github = "jcgay"
 gitlab = "jcgay"
 twitter = "jchristophegay"
 linkedin = "jcgay"

Coloration syntaxique
#

Elle s’active dans la configuration :

pygmentsCodeFences = true
pygmentsUseClasses = true

Et il faut ensuite générer le style avec la commande :

hugo gen chromastyles --style=trac > static/css/syntax.css

J’ai activé le rendu côté serveur mais on peut aussi utilisé une version déportée dans le navigateur avec ce thème.

C’est un point qu’il faut que je creuse encore un peu parce qu’en l’état le rendu n’est pas optimal, quand un bloc de code est un peu trop large on ne peut pas scrollé horizontalement… 😅

Commentaires
#

Les commentaires du blog étant hébergés sur Disqus, la migration s’est bien déroulée.
Il a suffit d’utiliser les bons disqus_identifier pour chaque article. Par contre au départ j’avais utilisé l’option delayDisqus = true pour ne pas charger les commentaires par défaut (ça alourdi pas mal les pages de charger Disqus) mais cette option ne respecte pas par la suite les disqus_identifier définis… Ce qui rendait la récupération des anciens commentaires impossibles.

Un de ces jours je jetterai un oeil aux alternatives disponibles 😇.

Redirections
#

La possibilité de définir des alias pour chaque article a été suffisant pour gérer la migration des URL des articles, les ressources statiques n’ont pas bougées. J’ai ajouté de nouvelles règles uniquement pour les flux RSS :

RewriteRule feed/?$ index.xml [R=301,L]
RewriteRule feeds/? index.xml [R=301,L]

Prévisualisation
#

Pour voir le rendu de ce qu’on est en train d’écrire :

hugo serve

Le contenu se recharche bien entendu à chaud.

Génération du site final
#

Le site prêt à déployer est disponible dans le dossier public après avoir lancé :

hugo

Conclusion
#

En 3 ou 4 heures j’ai réussi à avoir un rendu de mon blog à peu près équivalent au précédent.
Je ne pensais pas que la migration se passerait aussi facilement 😎.
Il reste 2 ou 3 réglages à faire mais je suis bien content de ne plus avoir à me compliquer la vie pour avoir un environnement stable Python pour générer ce site 🎇.

Migration de WordPress vers Pelican

Mon, 17 Mar 2014 20:31:00 +0200

Retour sur la migration d’un blog construit avec WordPress pour un site statique généré avec Pelican.

Mais pourquoi ?
#

Tout simplement pour avoir quelque chose de plus léger… J’avais volontairement gardé mon installation de WordPress minimaliste mais l’outil prends du poids par nature (en tout cas pour des fonctionalités que je n’utilisais pas). Peu de plugins étaient installés mais les temps de chargement ne me convenaient pas (hébergement mutualisé pour du PHP).

Comme j’écrivais déjà mes textes en Markdown pour les convertir en HTML et les coller dans l’éditeur de WordPress, j’ai sauté le pas pour un générateur de contenu statique.

Pelican
#

Pelican est un générateur de site statique écrit en Python. Il supporte Markdown, AsciiDoc et reStructuredText.
Il en existe une pléthore, les plus connus étant certainement Jekyll et Octopress.
J’ai choisi Pelican car il propose une fonctionalité multilangue, ce qu’il est possible de faire avec les autres mais pas de manière native.

Installation
#

Pour l’utiliser avec OS X :

brew install python
pip install virtualenv

## Install Pelican
mkdir -p ~/virtualenvs/pelican
virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
. bin/activate
pip install pelican
pip install Markdown
pip install beautifulsoup4
pip install typogrify
pip install webassets
pip install cssmin

Sinon l’installation est détaillée ici.

Activer l’environnement Pelican
#

. ~/virtualenvs/pelican/bin/activate

Quitter l’environnement Pelican
#

deactivate

Créer un site
#

Il suffit de lancer pelican-quickstart et de suivre les instructions.

Welcome to pelican-quickstart v3.3.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] blog
> What will be the title of this web site? Jean-Christophe Gay
> Who will be the author of this web site? Jean-Christophe Gay
> What will be the default language of this web site? [en] fr
> Do you want to specify a URL prefix? e.g., http://example.com (Y/n) Y
> What is your URL prefix? (see above example; no trailing slash) http://jeanchristophegay.com
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) Y
> Do you want to upload your website using FTP? (y/N) N
> Do you want to upload your website using SSH? (y/N) N
> Do you want to upload your website using Dropbox? (y/N) N
> Do you want to upload your website using S3? (y/N) N
> Do you want to upload your website using Rackspace Cloud Files? (y/N) N
Done. Your new project is available at /Users/jcgay/blog

Les source générées:

blog
├── Makefile
├── content
│   ├── (pages)
├── develop_server.sh
├── fabfile.py
├── output
├── pelicanconf.py
└── publishconf.py

2 directories, 5 files

Ajouter du contenu
#

Les articles doivent être ajoutés dans le dosser content. Il est possible d’extraire le contenu de WordPress pour l’importer dans Pelican : http://docs.getpelican.com/en/3.3.0/importer.html#import

Je ne l’ai pas testé car j’avais déjà des versions Markdown de mes articles. Je me suis contenté d’ajouter les métadonnées nécessaires à Pelican dans mes fichiers .md.

Pour qu’un article soit indexé comme tel par Pelican, il faut ajouter les métadonnées:

Title: git-p4 au secours de Perforce
Date: 2012-03-18 18:10
Category: Scm
Tags: git, git-p4, perforce, p4
Slug: git-p4-au-secours-de-perforce
Author: Jean-Christophe Gay
lang: fr

La propriété slug permettra de conserver les mêmes URLs que celles utilisées par WordPress.

Choisir un thème
#

Les thèmes sont disponibles dans le repository https://github.com/getpelican/pelican-themes.

Pour le moment j’ai choisi le thème elegant.

Cloner le répository des thèmes Pelican pour pouvoir les utiliser par la suite.

Les plugins
#

Pelican est extensible par l’intermédiaire de plugins. Ils sont répertoriés dans le repository https://github.com/getpelican/pelican-plugins. Comme pour les thèmes il suffit de cloner le repository dans l’emplacement de son choix.

La liste des plugins que j’ai activé:

sitemap : génère un fichier sitemap.xml pour l’indexation.
tipue_search : moteur de recherche au sein du site sans utiliser un service tiers.
extract_toc : extait une table des matières du contenu d’un article.
optimize_images : compresse les images jpeg et png.
related_posts : affiche une liste d’article en relation avec l’article lu.
summary : défini un résumé de l’article en utilisant le tag  dans les articles.
assets : permet de minifier/compiler les resources statiques.

Configuration
#

La configuration est séparée en deux fichiers: pelicanconf.py et publishconf.py. Le second surcharge le premier avec les paramètres utilisés lors de la génération du site de production.

Tous les paramètres sont documentés ici.

Je n’ai pas rencontré de difficultés particulières, deux petites astuces quand même.

Pour générer des URLs identiques à celles que j’avais avec WordPress :
```
 ARTICLE_URL = '{slug}'
 ARTICLE_SAVE_AS = '{slug}/index.html'
```

Pour chaque article, un dossier est créé avec la valeur de la métadonnée slug contenant un fichier index.html.

Il est possible de copier des fichiers avec la propriété EXTRA_PATH_METADATA :

 EXTRA_PATH_METADATA = {
 'extra/humans.txt': {'path': 'humans.txt'},
 'extra/robots.txt': {'path': 'robots.txt'},
 'extra/.htaccess': {'path': '.htaccess'},
 }

Les commentaires
#

Si vous utilisez le système de commentaires de WordPress, il faut les migrer vers un service externe, par exemple Disqus. C’est déjà ce que j’utilisais mais sinon il suffit d’installer le plugin WordPress.

Pour chacun des articles, ajouter l’identifiant de chaque fil de discussion :

disqus_identifier: 7 http://jeanchristophegay.com/?p=7

C’est supporté par le thème elegant.

Règles de redirection
#

Il faut réécrire les URLs qui vont disparaitre pour ne pas perdre toutes vos URLs qui se baladent dans la nature.

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule feed/?$ feeds/rss.xml [R=301,L]
RewriteRule wp-content/uploads/2013/03/Capture-d’écran-2013-03-09-à-11.24.20-300x182.png images/p4merge-mini.png [R=301,L]
RewriteRule wp-content/uploads/2013/03/Capture-d’écran-2013-03-09-à-11.24.20.png images/p4merge.png [R=301,L]
# Redirect wp-content/uploads/2012/03/git-p4.png to images/git-p4.png
RewriteRule wp-content/uploads/[0-2][0-9][0-9][0-9]/[0-1][0-9]/([^/]+) images/$1 [R=301,L]
# Redirect 2012/04 to archives.html#2012
RewriteRule ([0-2][0-9][0-9][0-9])/[0-1][0-9]/? archives.html#$1 [R=301,NE,L]
# Redirect category/slug/ to categories.html#slug-ref
RewriteRule category/([^/]+)/? categories.html#$1-ref [R=301,NE,L]
# Redirect tag/slug/ to tags.html#slug-ref
RewriteRule tag/([^/]+)/? tags.html#$1-ref [R=301,NE,L]
# Redirect author/jcgay/ to /
RewriteRule author/jcgay/? / [R=301,L]
</IfModule> 

Tester/Publier son site
#

Pour générer le site, lancer make html && make serve.
Le contenu est généré dans le dossier output et accessible via http://localhost:8000.

Le contenu final est disponible en utilisant make publish. Il ne reste qu’à uploader le contenu en ligne.

Conclusion
#

Je suis plutôt satisfait du résultat, tout le site est généré à partir d’un simple repository git, celà permet de versionner correctement le contenu du site et j’ai les fonctionalités nécessaires à la publication de quelques articles de temps en temps. Mission Accomplie !

Markdown on Jean-Christophe Gay

Migration de Pelican vers Hugo

Installation #

Theme #

Migrer les articles #

Configuration #

Site #

Coloration syntaxique #

Commentaires #

Redirections #

Prévisualisation #

Génération du site final #

Conclusion #

Migration de WordPress vers Pelican

Mais pourquoi ? #

Pelican #

Installation #

Activer l’environnement Pelican #

Quitter l’environnement Pelican #

Créer un site #

Ajouter du contenu #

Choisir un thème #

Les plugins #

Configuration #

Les commentaires #

Règles de redirection #

Tester/Publier son site #

Conclusion #

Installation
#

Theme
#

Migrer les articles
#

Configuration
#

Site
#

Coloration syntaxique
#

Commentaires
#

Redirections
#

Prévisualisation
#

Génération du site final
#

Conclusion
#

Mais pourquoi ?
#

Pelican
#

Installation
#

Activer l’environnement Pelican
#

Quitter l’environnement Pelican
#

Créer un site
#

Ajouter du contenu
#

Choisir un thème
#

Les plugins
#

Configuration
#

Les commentaires
#

Règles de redirection
#

Tester/Publier son site
#

Conclusion
#