Benoît Courtine



    Navigation
     » Accueil
     » A propos
     » XML Feed

    Simplification

    17 Aug 2016 » jekyll, asciidoc

    Introduction

    Pour rédiger efficacement de la documentation, je me suis intéressé récemment à différents formats d’écriture de type "markup" : markdown, textile, reStructuredText, Latex, Asciidoc, Docbook et Sphinx (voire peut-être quelques autres).

    Choix d’Asciidoc

    Je n’ai pas la prétention de les avoir tous étudiés à fond, ni d’avoir un avis très objectif, mais je suis rapidement devenu fan d’Asciidoc : pour mes besoins, le curseur entre fonctionnalités et simplicité de la syntaxe est juste au bon niveau (pour faire court, il est plus puissant que markdown/textile, tout en étant beaucoup moins verbeux que Latex/Docbook).

    Une recherche permet de rapidement trouver des argumentaires plus étayés…

    J’ai également apprécié Sphinx, mais ce qui m’a convaincu, ce sont les nombreux outils disponibles autour d’Asciidoc. En vrac (et j’en oublie sans doute) :

    • Les outils de génération (HTML/PDF/etc.) en ligne de commande.

    • Les plugins Atom pour gérer la syntaxe et la prévisualisation.

    • La librairie javascript asciidoctor.js, permettant d’obtenir un rendu des documents directement dans le navigateur.

    • DocGist, fournissant une interface web de rendu pour n’importe quel document accessible via une adresse web.

    • Jekyll, et son plugin Jekyll-Asciidoc, une solution Ruby très puissante de génération d’un site statique, à partir d’un répertoire source.

    • Hubpress, un moteur de blog pour Github Pages. Il est probablement encore plus simple à mettre en place que Jekyll et supporte nativement Asciidoc, mais il ne fonctionne qu’avec GitHub.

    Refonte du blog

    Ce langage étant agréable à utiliser, j’ai décidé de l’utiliser autant que possible… en particulier pour rédiger les articles de ce blog. C’est probablement possible via un plugin WordPress, mais je préfère rédiger mes différents documents dans Atom plutôt que dans un formulaire web. J’en suis donc à me dire que WordPress est une solution trop compliquée pour mes besoins.

    La perfection est atteinte, non pas lorsqu’il n’y a plus rien à ajouter, mais lorsqu’il n’y a plus rien à retirer.
    — Antoine de Saint-Exupéry
    Terre des Hommes

    Plutôt qu’une application avec une base de données, des plugins, thèmes… j’ai donc opté pour une nouvelle version du blog générée avec Jekyll. Voici une liste des avantages/inconvénients que j’y ai vus :

    Les inconvénients

    • Il n’est pas possible de rédiger un article en ligne (point qui ne me dérange pas, je préfère de loin un éditeur hors-ligne).

    • Le site généré étant statique, je perds la possibilité de laisser les visiteurs saisir des commentaires. Je peux rétablir la fonction avec Disqus, mais je perds l’hébergements des commentaires. Vu l’audience et le nombre de commentaires sur la précédente version… ce n’est pas une grande perte.

    • Les "widgets" de mise en page (pagination, calendrier des dates de publication, etc.) doivent être recodés en HTML/JS/CSS (mais c’est souvent très simple), ou intégrés via des plugions (Jekyll-paginate par exemple).

    Les avantages

    Le principal avantage est la simplicité (à tous les niveaux).

    • Les seuls outils nécessaires pour développer intégralement un blog Jekyll sont Git et un éditeur de texte.

    • Plus d’interface d’administration de type "tableau de bord d’avion de chasse", avec ses milliers d’options.

    • Pas de montées de version de sécurité à appliquer sur le moteur.

    • Un simple serveur http suffit pour servir les pages (ni PHP, ni base de données).

    • L’ensemble du site étant en gestion de configuration sous Git, la sauvegarde est naturellement intégrée (pas de dumps à planifier/archiver).

    • Le moteur de template des pages est puissant et très simple à prendre en main.

    • 3 templates simples suffisent pour avoir un site. C’est donc très facile à mettre en place et à adapter. On récupère complètement la main sur le code HTML qui est généré.

    Conclusion

    J’apprécie beaucoup cette approche, et j’en suis pour le moment très satisfait, même s’il me reste encore pas mal de choses à mettre en place dans mes templates, que j’ajouterai au fur et à mesure…

    Jekyll est développé en Ruby. Pour ceux qui préfèrent le langage "hype" du moment, il existe Hugo (que je n’ai pas testé). Il fonctionne sur le même principe, mais est développé en Go.

    N’ayant pas migré les archives du blog WordPress, celui-ci reste accessible à l’adresse https://archive.courtine.org/