Dev-Mind

Créer son blog en Asciidoc via Asciidoctor

09/05/2017
Web  Blog  Asciidoc  Asciidoctor  CMS 

Je suis rédacteur du blog JavaMind depuis maintenant 7 ans. Quand j’ai lancé le blog, j’ai choisi un CMS en ligne (Blogger) qui m’offrait de la souplesse mais qui n’était pas très personnalisable. Depuis un bon moment maintenant je cherchais une solution de remplacement simple et intégrable facilement dans mon site web.

Je suis très heureux d’annoncer que vous retrouverez dorénavant mes articles directement sur le site https://www.dev-mind.fr. Je vais essayer d’expliquer pourquoi et comment j’ai choisi de changer ma manière de publier mes articles pour passer d’un blog sous Blogger à un blog généré via node et Asciidoctor.

Nainformaticien

Remontons dans le temps

J’ai toujours eu du mal à retenir les choses si je ne les écrivais pas. Dès la fin de mes études, j’ai essayé de mettre au format numérique mes notes pour les retrouver plus facilement. Je n’ai pas retrouvé les sources de mon premier site perso mis en ligne en 1999 (merci Free). En 2001 j’ai lancé mon site nainformaticien.fr pour expliquer comment fonctionnait Internet, parler de programmation, et exposer mes photos de vacances…​

Nainformaticien

Bon forcément peu de personne ont lu ces pages hormis moi :-) Mais elles avaient le mérite d’être mon pense bête en ligne. C’est vrai qu’à cette époque, le site developpez.com lancé en même temps en 1999 avait déjà beaucoup plus de succès et mes photos de vacances n’intéressaient que moi.

Après cette prise de conscience, j’ai beaucoup moins publié sur Internet. Je souffrais un peu du syndrôme de l’imposteur. Je n’ai pas pour autant arrêté de documenter les sujets techniques que j’explorais mais je le faisais en interne pour le compte de l’entreprise où je travaillais à l’époque.

Et d’un point de vue technique

Premiers essais

Au départ mon blog était constitué d’une suite de pages. A chaque modification de structure il fallait repasser sur toutes les pages. Je suis passé par les iframes, la génération de code en JavaScript…​ Mais je n’étais pas satisfait.

Non pas de CMS…​

Les premiers CMS sont apparus mais en tant que développeur je n’avais pas envie d’aller vers des solutions toute prêtes. Avec les hébergements PHP gratuits, je me suis créé un petit framework MVC en PHP utilisant des templates, et qui me facilitait la création de pages. Je ne dénigre pas le langage PHP mais je n’ai jamais été vraiment fan. J’ai donc essayé de générer mon blog en Java. Mais je me suis rendu compte que des langages comme PHP ou Java ne simplifiaient pas grand chose et que mes solutions étaient un peu lourde pour servir quelques pages statiques…​

Eh ben si un CMS…​

Comme mes différents essais étaient non concluants je me suis résigné à utiliser un CMS en 2010. J’aurai pu mettre en place un site WordPress mais je voulais aller vite. J’ai donc choisi de publier mes articles sur un CMS en ligne et je me suis rabattu sur https://www.blogger.com. Certes la personnalisation est limitée mais ces outils visuels permettent de vite publier du contenu, de faciliter le référencement, de générer les liens pour relayer les articles sur les réseaux sociaux…​

Mais je veux mieux faire

Ce cadre imposé par les CMS m’a laissé insatisfait. Je préfère coder que paramétrer. J’ai donc continué d’expérimenter. J’ai créé des maquettes de blog écrites en Angular qui avaient le mérité d’être full stack web, de proposer des templates…​ Mais là je me suis heurté aux problèmes de référencements…​

J’ai testé Jekyll notamment via l’intégration sous Github pages. Ecrire des articles au format markdown est sympa, on se rapproche d’une solution qui me plait. Mais j’aimerai une solution que je puisse intégrer facilement à mon site institutionnel en modifiant simplement mon process de build existant…​

Ma solution idéale

Toutes ces expérimentations m’ont en fait permis de savoir ce que je voulais, qu’elle était ma solution idéale. Je parle de MA solution idéale car vous avez le droit de ne pas être d’accord avec moi.

Une solution idéale pour mettre en place un blog ou un site perso doit à mon sens proposer les choses suivantes

  • ne suivre que les technos standards du Web : HTML, JS et CSS. Si vous voulez un contenu indexé, lisible par tous, rapide à charger il est préférable d’implémenter des choses simples

  • avoir une solution de templating pour avoir la possibilité de changer facilement. Quand vous faites un site marketing le visuel doit évoluer pour montrer votre dynamisme

  • gérer le cycle de vie du site comme on gère un projet JS en 2017 avec un task builder. Pour ma part Gulp

  • écrire mes articles au format texte car c’est à mon sens le mieux pour pouvoir éditer, corriger, ajouter du contenu en ligne notamment via github. Par contre je souhaite que le formatage du contenu soit simple (texte, exemple de code, vidéos, images, tableau…​)

  • ne pas avoir de bases de données mais être capable d’indexer les articles afin de créer un écran de recherche de navigation entre mes articles

  • pouvoir héberger mon site sur un environnement mutualisé peu coûteux

  • être capable de dupliquer facilement le concept pour les différents sites associatifs que je gère (gestion technique et non éditoriale)

En 2015 la keynote de Dan Allen à MiXiT m’a inspiré. Mais comme beaucoup de personnes qui font de la veille technique j’ai incrit Asciidoctor tout en bas de ma liste des choses à creuser et comme ce sujet n’était pas prioritaire, je l’ai un peu oublié. En 2016 je me suis réveillé lors de l’intervention de Hubert Sablonière au Lyon Jug. Il était venu présenter l’écosystème Asciidoctor et il a réveillé mon besoin de mettre à jour mon site et mon blog. Je dois dire que j’ai eu un peu de mal pour démarrer car je ne pouvais facilement mettre en place mes templates avec Asciidoctor ni exploiter les métadonnées des documents.

Et là c’est la magie d’avoir des gens hyper réactifs et motivés sur des projets Open Source comme Asciidoctor. On branche un membre de la team

Twitter

En quelques jour j’avais tout pour démarrer à implémenter le blog de mes rêves dans mon site https://www.dev-mind.fr

Mon blog via Asciidoctor

Maintenant que j’ai expliqué le cheminement (le "pourquoi") je vais pouvoir parler un peu plus du "comment" arriver à ce résultat. Vous pouvez consulter les sources de mon site sur Github.

Ecrire les articles

Voici un exemple d’article en Asciidoc

----_
:doctitle: Créer son blog via Asciidoctor
:description: Migrer son blog de blogger vers un blog généré via Asciidoctor
:keywords: Web, Blog, Asciidoctor, CMS
:revdate: 2017-05-09
:teaser: Pourquoi et comment j\'ai choisi de changer ma manière de publier mes articles en passant de Blogger à un blog généré via Asciidoctor.
:imgteaser: ../../img/blog/unknown-a8aafc1038.png

Je suis rédacteur du blog JavaMind depuis maintenant 7 ans. Quand j’ai lancé le blog, j’ai choisi un CMS en ligne (Blogger) qui m’offrait de la souplesse mais qui n’était pas très personnalisable. Depuis un bon moment maintenant je cherchais une solution de remplacement simple et intégrable facilement dans mon site web.

Remontons dans le temps

Si vous voulez en savoir plus sur la syntaxe Asciidoc vous pouvez consulter la documentation.

Cycle de vie de mon site

Pour comprendre le cycle de vie de mon site web vous pouvez consulter le fichier de description du build Gulp. Les principales tâches sont

  • styles : compilation Sass en CSS, utilisaton de autoprefixer et minification des feuilles de styles

  • blog : compilation des fichiers Asciidoc et indexation des différents fichiers (je reviens plus tard sur le détail)

  • html : parsing des fichiers HTML de l’application (fichiers n’ayant pas un format article comme la page d’accueil) et utilisation de Handlebar pour appliquer des templates et générer le HTML

  • scripts : transpilation des scripts en ES5 puis minification

  • images : amélioration des images et convertion en format alternatif comme webp

  • service-worker : génération d’un service worker avec sw-precache et sw-toolbox pour les connexions dégradées ou le mode offline

  • compress : compression au format gzip des ressources statiques

Génération du blog

Regardons un peu plus en détail la partie de génération du blog

gulp.task('blog-indexing', () =>
  gulp.src('src/blog/**/*.adoc')
    .pipe(asciidoctorRead())
    .pipe(asciidoctorConvert())
    .pipe(asciidoctorIndexing('blog-index.json'))
    .pipe(gulp.dest('build/dist/blog'))
);

gulp.task('blog', ['blog-indexing'], () =>
  gulp.src('src/blog/**/*.adoc')
    .pipe(asciidoctorRead())
    .pipe(asciidoctorConvert())
    .pipe(applyTemplate('src/templates/blog.hbs'))
    .pipe(highlightCode({selector: 'pre.highlight code'}))
    .pipe(gulp.dest('build/.tmp/blog'))
    .pipe($.htmlmin(HTMLMIN_OPTIONS))
    .pipe(gulp.dest('build/dist/blog'))
);

La tâche blog-indexing permet de construire un index au format Json qui sera interrogeable via un simple fichier JS pour naviguer ou retrouver facilement un article de blog. La tâche blog convertit quand à elle, les articles Asccidoctor en HTML en utilisant les templates Handlebar.

asciidoctorRead, asciidoctorConvert, asciidoctorIndexing, …​ sont des extensions à notre build Gulp ou des scripts permettant de transformer les flux de données lus.

Gulp extension

Si le code JS de ces extensions vous intéresse je vous laisse consulter les sources sous Github. Le plus intéressant à exposer est la philosophie derrière

  • asciidoctorRead lit le stream des documents asciidoctor et interprète ces documents pour extraire le contenu HTML et les différentes metadata. Ce qui est super intéressant c’est que vous pouvez facilement ajouter vos propres métadonnées à vos documents.

  • asciidoctorConvert convertit les documents adoc en html

  • asciidoctorIndexing écrit les métadonnées dans un fichier (ici blog-index.json). Si votre site grossis vous pourriez par exemple mettre ces informations en base de données

  • applyTemplate utilisation de moustache pour insérer le contenu et les métadata dans un template de page (dans la première version j’avais utilisé Handlebar mais Mustache à l’intérêt de proposer de l’héritage entre les templates)

  • highlightCode mise en forme des blocs de code dans les pages avec highlight

  • …​

Les principales technologies utilisées sont les suivantes

  • Asciidoctor 1.5.6-preview.1 (en cours de développement)

  • Node > 7

  • Yarn

  • Gulp

  • Mustache pour les templates

  • Sass pour la définition des styles

  • Babel pour la transpilation ES5

  • highlights pour la mise en forme du code

  • …​

Pour finir

La solution que j’ai mise en place peut être encore améliorée notamment au niveau de la recherche de mes articles, de l’ajout de commentaires, …​ Mais Asciidoctor JS m’a permis de résoudre ma problématique assez facilement. Si vous avez des questions vous pouvez me contacter directement.


Article précédent : Des tests simples de vos services REST avec SpringBoot
Article suivant : Highcharts et staked area avec des valeurs négatives et positives Vous pouvez laisser un commentaire ou poser une question sur cet article par mail ou sur twitter.