Doc as code, personnaliser vos rendus pour répondre à vos contraintes ou à votre esprit créatif !

Produire 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 Asciidoctor¹.

Cette version de l'article a été publiée avec la chaîne de publication de l'écosystème Asciidoc².

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 Asciidoctor¹, 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 :

1. Les propriétés posées sur un document
2. Les paramètres passés sur la commande de génération
3. 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 CSS³.
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 Asciidoctor¹ permettent de générer vos documents au format HTML⁴.
Et comme tout bon HTML, il est possible de donner du style à nos écrits grâce à CSS³.

Selon votre degré de maîtrise du CSS³, 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>

1. La variable aasciidoctorconfigdir correspond au répertoire où se trouve le fichier .asciidoctorconfig
2. 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'Asciidoctor¹, 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-pdf⁵.
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>

1. la variable aasciidoctorconfigdir correspond au répertoire où se trouve le fichier .asciidoctorconfig
2. 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-pdf et non asciidoctor

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-pdf⁵.

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 HTML⁴/CSS³ 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...

1. https://asciidoctor.org/docs/ ↩

2. https://asciidoc.org/ ↩

3. https://www.w3schools.com/css/default.asp ↩

4. https://www.w3schools.com/html/default.asp ↩

5. https://docs.asciidoctor.org/pdf-converter/latest/ ↩