Thoth, un générateur de blog.
Table of Contents
Cela fait bien longtemps que ce blog n'a pas été mis à jour (et ce n'est pas la première fois que j'écris cette phrase).
Mais Wordpress était entièrement en ligne : rédiger les articles, ajouter des images, changer le thème, tout devait se faire en ligne. Progressivement certaines fonctions ont bénéficié d'un mode hors-ligne, mais qui demeurait une béquille. En outre, rédiger ses articles en local dans son éditeur de texte préféré impliquait de mettre de côté les images pour un futur upload, copier-coller le texte en espérant que la mise en forme soit conservée, rajouter les liens, etc. Et toujours une adresse en wordpress.com, ce qui signifiait des redirections, des modifications DNS pour rediriger depuis une URL personnelle (ou payer pour le pack Wordpress Pro). J'ai bien pensé à utiliser Wordpress en mode auto-hébergé, mais mon nom de domaine n'était associé qu'à une très faible quantité de stockage.
L'année dernière, j'ai découvert que Github proposait à ses utilisateurs d'héberger leur site sous forme d'un repository [2], synchronisé avec un dossier local. Le choix était laissé de tout coder à la main (un peu long pour rajouter un article sur un blog), ou d'utiliser Jekyll. J'ai ainsi découvert les générateurs de blogs statiques. Plutôt que de s'appuyer sur pas mal de PHP et une base de données (comme Wordpress le fait) pour générer les pages d'articles dynamiquement lorsque les visiteurs les consultent, ces utilitaires se contentent de générer en local les pages une bonne fois pour toutes, remettant à jour l'index, etc. A charge ensuite pour l'utilisateur de tout uploader.
Ce système proposait plus de personnalisation, une utilisation hors-ligne, la possibilité de rédiger des articles sous forme de simples fichiers textes formaté en Markdown en leur ajoutant un en-tête et en les plaçant dans un dossier articles, etc. Je suis alors passé sous Jekyll+Github, utilisant l'outil d'import depuis Wordpress qui m'a permis de convertir et conserver mes anciens articles.
Jekyll est un fabuleux outil, bien documenté et très personnalisable [3]. Mais il restait quelques détails qui me freinaient :
- une mauvaise gestion des images. Les articles devant être dans un dossier spécifique, le chemin relatif des images en local ne correspondait pas toujours au chemin sur le serveur. En outre, Jekyll ne détectait pas spécifiquement les images, il fallait donc les placer dans un des dossiers que Jekyll uploaderait automatiquement.
- des thèmes parfois dur à personnaliser, parce que la syntaxe utilisée est difficile à prévisualiser et propose trop de variations. De la même manière, créer son propre thème est du coup plus compliqué.
- pas de mise en ligne automatique, il faut soi-même uploader (via un client FTP ou en faisant un commit si l'on utilise Github).
D'autres détails n'étaient pas tant des problèmes que des éléments inutiles. Les en-têtes d'articles étaient parfois surchargés, le code HTML généré était lourd pour un simple blog avec quelques articles, etc. Entre temps, j'avais obtenu plus de stockage lié à mon site web, mais je ne me voyais pas revenir à Wordpress. Je continuais donc avec Jekyll.
L'histoire continue
Il y a quelques semaines (un peu avant le 9 février si j'en crois l'historique des commits), j'ai décidé de concevoir mon propre générateur de blogs, avec juste ce qu'il faut de fonctions. La liste de doléances était la suivante :
- le programme doit être en ligne de commande, et doit permettre en une ligne de générer le blog contenu dans le dossier passé en argument et l'uploader sur un ftp prédéfini.
- il doit permettre de différencier les articles achevés et les brouillons (drafts) qui sont mélangés dans un même dossier, et générer une page d'index pour chaque type.
- les articles sont en Markdown, peuvent comporter des notes de bas de page, leurs images doivent être copiées dans des dossiers spécifiques à chaque article avant l'upload. L'en-tête doit être le plus simple possible, juste un titre, une date et éventuellement un auteur. La taille des images doit pouvoir être spécifiée dans le fichier texte (contrairement au Markdown vanilla qui se contente de les afficher pleine taille).
- les thèmes doivent être facile à créer et personnalisables.
- l'upload vers un ftp doit pouvoir se faire automatiquement, en n'uploadant à chaque fois que ce qui est nécessaire.
Avec ces quelques exigences en tête, j'ai commencé à développer Thoth. Et après un petit mois de développement, Thoth est fini !
Bonjour, Thoth
Son vrai nom est {#Thoth}[4], il a été écrit en Swift. Son nom[5] est celui du scribe des dieux égyptiens, lui-même dieu du savoir, de l'écriture et de la lune. Bien entendu, je me suis appuyé sur plusieurs bibliothèques pour certains éléments techniques (parce qu'il ne sert à rien de réinventer la roue) :
- pour la partie conversion Markdown, j'utilise Markingbird - Markdown.swift. Je l'ai légèrement modifié pour extraire les notes de bas de page et les dimensions souhaitées pour chaque image, ainsi que les liens vers ces mêmes images pour pouvoir copier les originaux dans les dossiers d'articles.
- pour la gestion des connexions FTP, FTPManager. Programmé à l'origine en Objective-C, il a fallu simplement que je le bridge pour l'utiliser depuis mon code Swift.
- pour certains raffinements de l'utilisation en ligne de commande, swift-libedit a été utilisé.
Dans le même temps j'ai créé un thème HTML/CSS par défaut à utiliser, même s'il n'est pas inclut avec l'installeur (qui se contente d'installer l'utilitaire en ligne de commande dans /usr/local/bin).
Technique(s)
Thoth n'est pas très technique. Le plus difficile a été de garder un code propre et ordonné [6], même si le traitement très linéaire des différentes tâches (charger le thème, charger les articles, générer les pages des articles, générer l'index) ne nécessitait pas de déployer des trésors d'abstraction et d'orienté-objet.
Créer un outil en ligne de commande exige toujours d'être attentif au traitement des arguments saisis en entrée par l'utilisateur, et de parer à toutes les erreurs qu'il peut faire. L'utilisation du template pour générer des pages avec du contenu a été une partie très interessante du développement, il s'agit majoritairement de jeux sur des chaines de caractères. Les footnotes, bien qu'un peu plus difficiles à mettre en oeuvre, étaient sinon du même acabit. La gestion des images et leur récupération s'est révélée plus simple que ce que j'appréhendais (la classe NSFileManager gérant d'emblée la plupart des erreurs et exceptions pour moi).
Thoth aura surtout été l'occasion de se familiariser avec Swift, et comprendre comment le faire interagir avec du code Objective-C, et comment les principales classes de Core Foundation s'y retrouvaient.
Vers le futur
Thoth a été développé assez rapidement, et n'est pas à l'abri de bugs, même si quelques tests ont été effectués par mes soins. La partie FTP notamment a du mal à gérer certaines connexions et les conflits. Les footnotes ne sont pour le moment traitées qu'inline. Les fichiers sitemap.xml et feed.xml ne sont pas générés. Le code est peu commenté et parfois mal rangé.
Mais Thoth est avant tout conçu égoïstement pour mon propre usage. Je suis conscient du fait qu'il ne conviendra probablement pas à grand monde, mais au cas où voici quelques instructions d'installation. La version complète en anglais est disponible sur le repo git.
Instructions
Après avoir installé Thoth, le plus simple est de le laisser créer un dossier pour votre blog, à l'endroit désiré :
$ thoth setup /chemin/vers/le/futur/dossier/du/blog
Thoth va automatiquement créer les dossiers nécessaires à son fonctionnement et un fichier de config, à remplir consciencieusement une bonne fois pour toute (même si les réglages ont tous une valeur par défaut, et vous n'êtes pas obligés d'indiquer la partie FTP si vous ne comptez pas vous en servir).
Ajoutez alors un template dans le dossier correspondant. Vous pouvez télécharger le mien depuis ici (sur le repo). Les fichiers index.html et article.html doivent être à la racine du dossier template.
Mettez vos articles dans le dossier articles, vos images où vous voulez du moment que les liens en local sont bons.
Pour la première génération, utilisez la commande
$ thoth first /chemin/vers/le/dossier/du/blog
Si vous ne voulez pas utiliser le FTP mais simplement générer une copie du blog en local, utilisez plutôt
$ thoth generate /chemin/vers/le/futur/dossier/du/blog -f
Ensuite, pour mettre à jour le blog après avoir écrit un article ou un brouillon, lancez
$ thoth scribe /chemin/vers/le/dossier/du/blog
ou de façon équivalente
$ thoth /chemin/vers/le/dossier/du/blog
ou
$ thoth generate /chemin/vers/le/futur/dossier/du/blog
pour une mise à jour en local. Les brouillons sont consultables via la page ` index-drafts.html`.
Particularités syntaxiques
Les notes de bas de page utilisent la syntaxe [ ^ contenu de la note].
La taille d'une image doit être spécifiée dans son titre, comme suit :
ou juste
Si aucune taille n'est précisée, la largeur par défaut indiqué dans le fichier de configuration sera utilisé. Dans tous les cas, les images en local seront copiées dans un dossier spécifique à l'article.
Plus de détails sur les commandes, leur liste complète, les différentes options, la création de thèmes en utilisant des mots-clés,... sont disponibles sur le repository.
Bien sûr, mon blog est désormais généré par Thoth !