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 :
-
Beaucoup de langages supportés.
-
Possibilité de générer les styles en
inlineou d’utiliser des feuilles de style CSS. -
De nombreux thèmes disponibles.
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" :
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 :
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 :
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.
|
rougify style base16.solarized.dark > css/asciidoc-rouge.css<!-- Coloration syntaxique du code -->
<link rel="stylesheet" href="{{ site.stylesdir | prepend: site.baseurl }}/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é.