AsciiDoc est un format textuel qui permet d’écrire des documents (livres, ebooks, articles, pages web, blogs, …). Il est particulièrement pratique pour les documentations techniques.
AsciiDoc propose un langage textuel. L’utilisation d’un format textuel a plusieurs avantages :
- l’édition ne nécessite pas d’outil particulier : un simple éditeur de texte suffit
- le document est ainsi facilement lisible et modifiable
- deux versions d’un document sont très facilement comparables
- la taille des documents est très légère
Pour améliorer la productivité de la rédaction d’un document AsciiDoc, il est possible d’utiliser des outils qui prévisualisent le rendu du document et assure une coloration syntaxique. Cela permet de rapidement corriger les erreurs de syntaxe.
L’outil AsciiDoctor et son écosystème sont utilisés pour transformer un document AsciiDoc afin de générer des documents dans différents formats publiables (HTML, DocBook, PDF, ePub, …).
La définition d’un document
Les fichiers AsciiDoc ont généralement l’extension .adoc.
Un document AsciiDoc est un fichier texte qui débute par des informations générales (titre du document, auteur(s), versions) et des attributs :
= Titre du document
Nom de l’auteur
v1.0, 2018-06-11
:toc:
:imagesdir: imagesAsciiDoc prédéfinit de nombreux attributs qu’il va utiliser pour sa configuration. Il est aussi possible de définir ses propres attributs. Dans tous les cas, la valeur d’un attribut s’obtient avec la syntaxe suivante :
{nom_attribut}Il est possible d’inclure des fichiers dans un fichier AsciiDoc en utilisant la macro include
include::chapitre_01.adoc[]
Le formatage du texte
Le texte est organisé en paragraphe : il n’y a pas de syntaxe particulière pour les délimiter. Les lignes de texte adjacentes ou consécutives forment un paragraphe. Pour en commencer un nouveau après un autre élément il suffit d’utiliser une ligne vide.
Un retour chariot n’apparait pas dans les documents générés. Il est possible de forcer un retour chariot à la fin d’une phrase en utilisant un espace suivi du caractère plus.
Première ligne du paragraphe.
Elle se poursuit avec une seconde ligne qui fait elle même partie du paragraphe
Texte avec saut de ligne force +
Ligne suivante
Une barre de séparation horizontale est définie en utilisant
'''Il est possible de demander un saut de page en utilisant
<<< Une syntaxe particulière permet de formater du texte
normal
_italique_
*gras*
+mono+
''double quote''
'simple quote'
E=mc^2^
H~2~O
Les commentaires sur une ligne commencent par un //
// commentairePlusieurs séquences sont remplacées par des caractères Unicode particuliers
(C) (TM) -> <= ... €
L’échappement des caractères spécifiques peut se faire de deux manières :
\*gras*
+++*gras*+++
Les titres des sections
AsciiDoc propose plusieurs formats pour les titres des sections :
Asymetric atx-style : c’est le style recommandé car c’est le plus simple à mettre en œuvre. Défini sur une seule ligne, le titre est précédé d’un ou plusieurs caractères = qui indique le niveau de la section
= Titre du document
== sous-titre niveau 1
=== sous-titre niveau 2
==== sous-titre niveau 3
===== sous-titre niveau 4
====== sous-titre niveau 5Symetric atx-style : il s’utilise comme le style Asymetric atx-style mais il impose en plus de terminer le titre par la séquence de délimitation
== sous-titre niveau 1 ==Setext-style : c’est le style historique qui définit le titre sur deux lignes. La première contient le titre et la seconde est un ensemble d’un caractère répété pour souligner le titre. Chaque niveau est défini grâce à un caractère particulier : =, -, ~, ^, et +. L’utilisation de ce style n’est plus recommandé.
Titre du document
=================
sous-titre niveau 1
-------------------
Les listes
Plusieurs types de liste sont supportés par AsciiDoc. Chaque liste peut avoir un titre optionnel défini avec le caractère .
Les listes non ordonnées
Elles sont définies avec le caractère *
.Les formats supportés
* XML
* JSON
* YAML
Les listes peuvent imbriquer différents niveaux simplement en utilisant autant de caractères * que le niveau souhaité.
* Technologies front
** JavaScript
** CSS
* Technologies back
** Java
** Node JS
Les listes ordonnées
Elles sont définies avec le caractère . suivi d’un espace et supportent aussi le multi-niveau
.Les éléments ordonnés sont :
. élément 1
. élément 2
.. élément 21
.. élément 22
. élément 3
Les listes avec étiquettes
Elles sont définies en séparant l’étiquette et la définition avec ::
Par défaut, le rendu se fait sur deux lignes : la première contient l’étiquette et la seconde la description
.Type de mémoire
RAM:: Random Access Memory
ROM:: Read Only Memory
NVRAM:: Non volatile random access memory
Il est possible de demander le formatage sur une seule ligne
[horizontal].Type de mémoire RAM:: Random Access Memory ROM:: Read Only Memory NVRAM:: Non volatile random access memory
Les checklists
Elles sont définies avec un tiret suivi d’une paire de crochet qui précise l’état de la tâche. Une étoile ou un x sont utilisés pour indiquer que c’est coché.
. Tâches à faire
- [*] Tache 1
- [x] Tache 2
- [ ] Tache 3
- [ ] Tache 4
Les liens
AsciiDoc reconnait automatiquement les liens vers :
- http
- https
- ftp
- irc
- mailto
- email@www.oxiane.com
Il est possible de préciser le libellé du lien entre crochets :
http://www.www.oxiane.com[Site Oxiane]
Les blocs
Les blocs permettent de structurer du texte qui ne sont pas des paragraphes.
Différents types de blocs sont utilisables. Ils se définissent avec une suite d’au moins quatre caractères selon leur type et se terminent avec la même suite de caractères. Il est recommandé de n’utiliser que quatre caractères.
| Séquence de caractères | Rôle |
---- | Bloc permettant de délimiter un contenu généralement pour du code source |
//// | Bloc de commentaires |
.... | Bloc littéral : restitue le texte tel qu’il est fourni |
==== | Bloc exemple |
**** | Bloc de type sidebar : le contenu est restitué en dehors du flux |
____ | Bloc de type citation ou verset |
Les tableaux
Un tableau est défini comme un bloc particulier avec la séquence |===
Chaque cellule du tableau est définie avec un caractère |
|===
|Firefox
|Chrome
|Safari
|===
Par défaut, le nombre de colonnes est déterminé par la première ligne qui suit le délimiteur de tableau.
|===
|Browser |Version
|Firefox
|60
|Chrome
|66
|Safari
|11
|===
Il est possible de préciser explicitement le nombre de colonnes
[cols=2]
|===
|Browser
|Version
|Firefox
|60
|Chrome
|66
|Safari
|11
|===
La configuration d’un tableau peut être très pointues avec une syntaxe dédiée.
[%header%footer,cols="2,2s,3",grid=rows,frame=topbot,width=100%,caption=Organisation]
|===
|Nom |Fonction |Twitter
|D Martin
^m|PDG
|mailto:dmartin@societe.fr[dmartin@societe.fr]
|JF Dupond
^m|DG
|mailto:jfdupond[jfdupond@societe.fr]
3+^.e|Les dirigeants
|===
Il est aussi possible de créer facilement un tableau en utilisant des données au format CSV
[%header,format=csv]
|===
Nom,Type,Description
Java,Langage,Langage de programmation polyvalent
Linux,Système d'exploitation,OS libre de type Unix
Apache,Serveur,Serveur web
|===
Les images
Il est possible d’ajouter des images en utilisant la syntaxe image:: suivi du chemin de l’image puis d’une paire de crochets qui peut contenir un texte alternatif.
image::logo_oxiane.jpg[Logo Oxiane]Le chemin est relatif par rapport à l’attribut imagesdir du document
Le code source
AsciiDoc permet d’intégrer du code source dans le document. AsciiDoctor supporte plusieurs outils de coloration syntaxique qui pourront améliorer la lisibilité du code dans les documents générés.
.Exemple 1
[ source,java]
----
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello world");
}
}
----
Il est possible d’inclure un fichier contenant le code source.
[ source,java]
----
include::HelloWorld.java[]
---- Il est aussi très pratique d’indiquer des renvois numérotés pour commenter le code.
.Exemple 3
[ source,java,numbered]
----
public interface Affichage { // #
void afficher(); // #
} // #
----
déclaration de l'interface
déclaration de la méthode public abstract
fin de la déclaration 
Plusieurs autres syntaxes sont aussi supportées :
.Exemple 4 XML
[ source,xml]
----
Martin
Pierre
----
Les diagrammes UML
AsciiDoctor Diagram est un ensemble d’extensions AsciiDoctor pour générer des diagrammes à partir d’une description textuelle qui seront inclus dans les documents générés. De nombreux formats sont supportés : AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite et WaveDrom. Il est ainsi possible de définir un diagramme de classes par exemple avec PlantUML.
[ plantuml, diagram-classes, png]
....
interface Interface
class Mere <> {
{static}-champ1
#champ2
{abstract}~methode1()
+methode2()
}
class Fille1
class Fille2
Interface <|-- Mere
Mere <|-- Fille1
Mere <|-- Fille2
note "mon commentaire" as N1
....
Un autre exemple avec un diagramme de séquence
[ plantuml]
----
IHM -> Service : getData
Service DAO : save
----
Les admonitions
Elles permettent d’attirer l’attention sur certaines informations avec un niveau de priorité défini grâce à une étiquette en majuscules :
- NOTE (remarque),
- TIP (conseil),
- IMPORTANT,
- CAUTION (avertissement),
- WARNING (attention)
WARNING: Son utilisation en production n'est pas recommandée.
Conclusion
Cet article n’est qu’une introduction aux fonctionnalités de base d’AsciiDoc qui propose par ailleurs de nombreuses fonctionnalités avancées comme la génération d’une table de matière ou d’un index, des notes de bas de pages (foot notes), …
Les fonctionnalités sont aussi accrues grâce au support de nombreux outils tel que la génération de diagrammes, syntax highlighter (Rouge, Pigment, …)
Le rendu de nombreux éléments peut aussi être personnalisés. AsciiDoctor s’intègre aussi parfaitement avec une solution d’intégration continue.
AsciiDoc connait un succès grandissant comme en témoigne la richesse de son écosystème.