Synopsis

J’utilise le script blog.rb ainsi qu’un ensemble de gabarits RHTML (traitables à l’aide d’erb/eRuby). Ce système maintient mon blogue statique en reconstruisant incrémentalement les pages et fils d’articles HTML en se fiant aux sources dont ils dépendent qui ont changé. Les fichiers pertinents au développement de ces outils sont maintenus dans ce dépôt Git.

Usage et modification

Tout le contenu du blogue est rédigé dans des fichiers Markdown, dans le sous-répertoire post du dépôt. Ces fichiers comportent un en-tête composé de directives précédées d’un signe de pourcentage (%), lesquelles indiquent le titre de l’article, son auteur, la date de publication, les étiquettes de classification… Voici un exemple:

% titre  "Titre de l'article."
% auteur "Auteur McBrillant", "adresse@courri.el"
% date   "2013-04-05 21:30"
% etiq   "Hommage", "Poesie", "Pas tant que ça"
% resume
À partir d'ici, on écrit le résumé de l'article, qui sera publié dans le
fil d'articles principal, ainsi que les fils spécifiques aux étiquettes.
% texte
Le texte principal commence ici. Si on écrit un article court qui peut
être publié au complet dans le fil principal, on peut omettre les
directives `% resume` et `% texte`. Dans ce cas, l'article ne comporte
aucun résumé, seulement un texte principal.

L'en-tête ci-haut omet par ailleurs la directive `% statique`. Cette
directive permet d'identifier un article comme une page statique, qui
n'apparaîtra pas dans les fils d'articles. On pourra y accéder si un lien
vers cette page est ajouté à un document ou à l'un des gabarits RHTML.

Il y a finalement la directive `url "<lien URI>"` qu'on peut utiliser pour
remplacer le lien vers lequel on navigue en cliquent sur le titre d'un
article depuis un fil. Par défaut, ce lien mène vers la page spécifique de
l'article. Cependant, lorsqu'on veut brièvement commenter un autre texte
sur le web, on peut lier ce texte au titre de notre article, omettre le
résumé et écrire le commentaire en guise de texte. Pour indiquer que le
titre mène hors du blogue, il est suffixé d'un symbole spécial.

À partir de ces sources au format Markdown, le script blog.rb (présent dans le répertoire post) composera, dans le sous-répertoire html:

• Une page nommée article.html pour toute source nommée article.md. Il s’agit du texte complet de l’article. Les pages sont composés en insérant le contenu de l’article dans le gabarit RHTML page.rhtml, dont le résultat est lui-même inséré dans le gabarit base.rhtml pour former la page finale.
• La page index.html, qui articule le fil des huit derniers articles. Ces articles sont insérés dans le gabarit post_list.rhtml, donnant le contenu à rendre via le gabarit principal base.rhtml pour former la page finale.
• Des pages nommées tag_<etiq>.html, qui articulent le fil de tous les articles respectivement classés avec l’étiquette <etiq>. Ces pages sont formés à l’aide des mêmes gabarits que index.rhtml.
• La page tags.html, qui constitue un index de toutes les étiquettes. Cette liste d’étiquettes est composée à l’aide du gabarit tags.rhtml et le résultat est à son tour inséré dans le gabarit base.rhtml.
• Le fichier feed.rss, le fil RSS des huit derniers articles tel que publiés sur le fil principal.

Ces pages HTML s’ajoutent au contenu fixe du blogue, déjà présent dans le sous-répertoire www: il s’agit des images (dans le sous-répertoire www/img) et du fichier de style style.css. Après l’exécution sans erreur de blog.rb, on peut aisément propager le blogue sur le serveur web à l’aide de la commande rsync, ou encore de tout autre logiciel FTP/SFTP. Dans le dépôt distribué, le sous-répertoire www ne contient aucun fichier HTML ni RSS statique; il est donc permis de supprimer tout le contenu généré automatiquement par blog.rb en effaçant bêtement tous les fichiers HTML et RSS présents dans www.

Pour qui est familier avec HTML, CSS et l’outil erb du langage ruby, le blogue peut être réorganisé et restylé simplement en modifiant les gabarits RHTML page.rhtml, post_list.rhtml, tags.rhtml et base.rhtml (tous dans le sous-répertoire post), ainsi que le fichier statique de style www/style.css. Ces gabarits n’affectent pas, en principe, la logique de génération des pages et fils d’articles mise en oeuvre par blog.rb.

Trucs pour rédiger le blogue sous Git

Comme je désire partager le logiciel d’assemblage du blogue, mais pas les sources de mes propres articles, j’ai mis au point un truc utilisant Git pour me permettre de développer les deux indépendamment. Le script et les gabarits de base, tels que partagés blog.git, sont développés sur la branche master de mon dépôt local. C’est cette branche qui est propagée sur le dépôt sur ce serveur. Pour la rédaction de mes sources et les ajustements fin au style du site, j’ai démarré une branche nommée redac, basée sur master.

Donc, quand j’écris un nouvel article, je le commets sur redac. Cependant, si je découvre un problème dans le script ou les gabarits, ou si j’ajoute une caractéristique à ces outils, je l’ajoute plutôt sur la branche master. J’intègre ensuite cette modification à la branche redac en la rebasant sur master. Cette opération permet de reconstruire une branche en ré-empilant les changements spécifiques d’une branche sur une nouvelle racine (la branche de base). Cela évite les historiques de changements hyper-compliqués inhérents à la maintenance parallèle de deux branches dont l’une dépend de l’autre.

En résumé, si je veux modifier mes outils pour régler un problème ou les améliorer, je fais:

git checkout master
# Diverses modifications et commissions.
git checkout redac
git rebase master

Durant le rebasage, il arrive que certains fichiers soient difficiles à fusionner avec une version distincte sur la base, causant des confilts. Ceux-ci sont généralement faciles à régler à la main, suite à quoi l’opération de rebasage peut être reprise par la commande

git rebase --continue

Si je comprends mal cependant la source du conflit, je peux rapidement annuler le rebasage par la commande

git rebase --abort