Nicolas GiraudProduire des documents avec les outils de doc as code reste quelque chose d'accessible à quiconque travaillant avec un IDE.
Toutefois, nos structures nous contraignent à utiliser des visuels pour produire ces documents, qu'ils soient internes ou externes.
Palettes de couleurs, chartes graphiques, design systems, sont des exemples de contraintes à appliquer dans nos processus de partage d'informations.
Le parcours initiatique pour publier, vous a peut-être conduit jusqu'ici.
Si la joie d'avoir publié vos premiers documents est bien là, la frustration qu'ils ressemblent à tous les autres n'est sûrement pas loin.
Mais comment personnaliser vos styles pour que vos documents web ou traitement de texte ne ressemblent pas à tous les autres ?
Je vous invite ici à découvrir quelles sont les possibilités de ces outils et d'identifier les points limitant pour votre créativité.
Mais avant tout, je dois vous présenter les différentes façons de configurer le générateur Asciidoctor1.
Cette version de l'article a été publiée avec la chaîne de publication de l'écosystème Asciidoc2.
Configurer le générateur
Produire et partager des documents reste relativement aisé.
Pour autant, si vous avez besoin de les personnaliser, vous devrez vous armer de patience pour configurer vous outils de génération.
Il existe un ensemble de propriétés permettant de surcharger les comportements par défaut du générateur Asciidoctor1, et ainsi appliquer vos propres styles.
Par défaut, nous allons pouvoir utiliser des fichiers de configuration pour adapter le comportement du générateur pour un ensemble de documents.
Des propriétés pourront aussi être définies directement dans chaque document pour surcharger les fichiers de configuration.
Il sera également possible de passer des paramètres communs en les ajoutant à la commande de génération.
L'ordre de priorité des paramètres est :
- Les propriétés posées sur un document
- Les paramètres passés sur la commande de génération
- La configuration fichier
Une fois que vous aurez réussi à configurer votre générateur, la suite de votre aventure se passera dans des fichiers CSS3.
En fonction de votre spectre de compétences, cette personnalisation vous sera plus ou moins accessible.
Malheureusement, je ne pourrai pas vous montrer ici les méandres de ce langage et vous laisserai explorer ses possibilités.
Personnaliser une feuille de style
Dans le petit guide illustré pour mieux se lancer, vous avez pu découvrir que les outils de docs as code comme Asciidoctor1 permettent de générer vos documents au format HTML4.
Et comme tout bon HTML, il est possible de donner du style à nos écrits grâce à CSS3.
Selon votre degré de maîtrise du CSS3, vous pourrez partir d'une feuille de style existante, ou en écrire de nouvelles en intégralité.
L'écriture intégrale d'une feuille CSS impliquera une bonne maîtrise de la structure HTML générée.
Vous devrez pour cela vous plonger dans Asciidoctor pour connaitre ce qu'il produit.Je vous préconise de repartir d'un thème existant afin de minimiser l'effort de compréhension du HTML généré.
Une fois votre feuille écrite, ou modifiée, il faut maintenant l'appliquer à vos documents.
Comme vu dans la section précédente, voici les trois méthodes possibles.
.asciidoctorconfig:
:stylesdir: {asciidoctorconfigdir}/.asciidoctor <1>
:stylesheet: fundation-lime.css <2>
- La variable
aasciidoctorconfigdircorrespond au répertoire où se trouve le fichier.asciidoctorconfig - Nom complet du fichier dans le répertoire.
On pourra utiliser de la même façon ces propriétés directement dans les fichiers sources.
En revanche, leur portée est au niveau fichier, et non générateur
Les mêmes propriétés pourront également être passées dans la ligne de commande.
command line:
asciidoctor -a stylesdir=.asciidoctor -a stylesheet=fundation-lime.css docs-as-code-03-styles.adoc
Du style dans vos PDF
Si vous souhaitez utiliser les fonctionnalités de génération PDF d'Asciidoctor1, la personnalisation des rendus sera quelque peu différente de nos habitudes de développement.
La production de PDF se fait grâce au plugin asciidoctor-pdf5.
Cet outil n'utilise pas CSS pour appliquer son style, mais un fichier de configuration YAML.
.exemple de fichier de template
extends: base
page:
layout: portrait
margin: [0.75in, 1in, 0.75in, 1in]
size: Letter
base:
font-color: #333333
font-family: Times-Roman
font-size: 12
line-height-length: 17
line-height: $base-line-height-length / $base-font-size
role:
removed:
font-style: italic
text-decoration: line-through
text-decoration-color: #FF0000
heading:
font-color: #262626
font-size: 17
font-style: bold
line-height: 1.2
margin-bottom: 10
link:
font-color: #002FA7
list:
indent: $base-font-size * 1.5
Pour plus de détails sur ces fonctions de personnalisation, vous pouvez vous reporter à la documentation du plugin.
Comme pour le CSS, nous allons maintenant devoir appliquer cette configuration au générateur PDF.
.asciidoctorconfig
:pdf-themesdir: {asciidoctorconfigdir}/.asciidoctor <1>
:pdf-theme: pdf <2>
- la variable
aasciidoctorconfigdircorrespond au répertoire où se trouve le fichier.asciidoctorconfig - Préfixe du fichier de configuration. Dans ce cas, le fichier s'appelle
pdf-theme.yml
On pourra utiliser de la même façon ces propriétés directement dans les fichiers sources.
En revanche, leur portée est au niveau fichier, et non générateur
Les mêmes propriétés pourront également être passées dans la ligne de commande.
Ligne de commande
asciidoctor-pdf --theme pdf -a pdf-themesdir=.asciidoctor docs-as-code-03-styles.adoc
L'exécutable est bien ici
asciidoctor-pdfet nonasciidoctor
Libérer votre créativité
Si la génération HTML offre de plus larges possibilités en matière de personnalisation de visuel, il semble intéressant de ne pas oublier les possibilités offertes par asciidoctor-pdf5.
D'un côté, la configuration dans des formats paginés à destination de l'impression demande une maîtrise particulière des différents attributs offerts par les outils.
Heureusement, leur documentation dense décrit les possibilités du plugin.
Il sera nécessaire de la parcourir afin d'obtenir le rendu souhaité.
De l'autre côté, l'écosystème HTML4/CSS3 permet de revenir dans un monde qui nous est peut-être plus proche : celui du développement.
Toutefois, les limites posées par la sémantique HTML proposée par asciidoctor apportent des contraintes qui peuvent s'avérer limitantes.
La prise de connaissance des subtilités de ces outils est chronophage, et vous risquez malgré tout de ne pas atteindre le résultat attendu.
Comme je vous l'ai montré dans l'article précédent, il existe un outil d'agrégation de documentation appelé Antora.
Cet outil, même s'il est basé sur Asciidoctor, utilise un moteur de templating plus complexe.
Et si les compétences en HTML/CSS peuvent rapidement être le facteur limitant de nos générations basiques, il en existe d'autres si vous utilisez Antora.
Mais ceci est une autre histoire...
