Benoît Courtine



    Navigation
     » Accueil
     » A propos
     » Mentions légales
     » XML Feed

    Jekyll, Asciidoctor, et coloration syntaxique

    19 Jan 2019 (MAJ le 22/01/2019 à 21:14) » jekyll, asciidoctor

    Mise en place initiale de la coloration syntaxique avec Pygments

    Lorsque je décidai de migrer vers un générateur statique pour mon blog, j’avais noté quelques prérequis :

    • Support de la syntaxe Asciidoc.

    • Coloration syntaxique du code.

    Jekyll étant développé dans le même langage qu’Asciidoc, (en Ruby), je supposai que l’intégration serait meilleure. Plusieurs colorateurs syntaxiques étaient possibles, mais le seul que je réussis à faire fonctionner convenanblement avec Jekyll et Asciidoc fut Pygments.rb. C’est d’ailleurs celui qui est officiellement recommandé pour le plugin jekyll-asciidoc.

    Il a de nombreux avantages :

    Mais il a aussi un inconvénient : Pygments est un colorateur syntaxique écrit en Python. Python.rb "juste" est un wrapper Ruby autour de Pygments. Mais ce wrapping un coût : il rent la génération du site plus lente.

    Rouge est un colorateur syntaxique écrit en Ruby. Il présente les mêmes avantages que Pygments (et leurs thèmes sont compatibles), tout en étant beaucoup plus rapide.

    Si je ne l’ai pas retenu lors de la mise en place, c’est parce que le ticket Asciidoctor le concernant, ouvert en 2014, n’est toujours pas fermé…​ Cependant, un développeur a proposé en 2017 le plugin Asciidoctor-Rouge, implémentant son support.

    Il existe d’autres colorateurs utilisables avec Asciidoctor, mais je ne les ai que survolés. Ils m’ont paru plus "légers" que les deux listés ci-dessus : je ne les ai donc pas retenus.

    Les autres colorateurs disponibles (à ma connaissance) :

    Mise en place de Rouge

    Je n’ai pas trouvé de tutoriel sur la combinaison Jekyll/Asciidoctor/Rouge, mais on peut s’en sortir sans trop de difficultés en combinant les différentes documentations. Pour ceux qui n’ont pas la patience, voici les fichiers à utiliser "clés en main" :

    Gemfile
    source 'https://rubygems.org'
    
    gem 'jekyll', '~> 3.8.5'
    gem 'asciidoctor', '~> 1.5.8'
    gem 'rouge', '~> 3.3.0'
    
    group :jekyll_plugins do
      gem 'jekyll-asciidoc'
      gem 'asciidoctor-rouge'
      (1)
    end
    1 Autres plugins Jekyll : jekyll-paginate, jekyll-last-modified-at…​

    Dans la configuration de Jekyll, ajouter la partie suivante à la configuration Asciidoc :

    Extrait de _config.yml
    asciidoctor:
      attributes:
        source-highlighter: rouge
        rouge-css: style
        rouge-theme: base16.solarized.dark (1)
    1 Thème à choisir parmi ceux disponibles : base16, base16.dark, base16.light, base16.monokai, base16.monokai.dark, base16.monokai.light, base16.solarized, base16.solarized.dark, base16.solarized.light, colorful, github, gruvbox, gruvbox.dark, gruvbox.light, igorpro, molokai, monokai, monokai.sublime, thankful_eyes, tulip.

    Cette configuration permet de valider rapidement le bon fonctionnement de la coloration syntaxique. Cependant, les styles sont inlinés dans chaque page, ce qui peut être amélioré. Pour cela, on doit créer un fichier des styles de coloration syntaxique Rouge, l’intégrer au template d’entête des posts, et modifier la configuration :

    Extrait de _config.yml avec utilisation de classes CSS
    asciidoctor:
      attributes:
        source-highlighter: rouge
        rouge-css: class
        stylesdir: /css
    Pour générer la feuille de style, Rouge vient avec l’outil rougify qui peut s’en occuper.
    Génération de la feuille de style
    rougify style base16.solarized.dark > css/jekyll-rouge.css
    Extrait du template des entêtes de posts
    <!-- Coloration syntaxique du code -->
    <link rel="stylesheet" href="{{ site.stylesdir }}/asciidoc-rouge.css">

    Bilan

    Le bilan est complètement positif :

    • Aucune régression à signaler par rapport à Pygment.

    • Le temps de génération du site a diminué de plus de moitié.