Asciidoc

Tags:
Categories:

Syntax

Étant donné qu’AsciiDoc est proposé comme un « système complet », incluant langage et interpréteur, il existe une syntaxe centrale. Contrairement à Markdown, AsciiDoc ne connaît ni variantes ni dialectes.

Commentaires

Le code AsciiDoc peut être commenté, comme tout autre code source. Cela signifie que les commentaires ne sont pas pris en compte lors de l’interprétation du texte source (par exemple, lors de la conversion en PDF). Cela permet d’ajouter des commentaires à des documents ou à des parties de texte, ou de laisser des notes.


Ceci est un texte quelconque en AsciiDoc.

// Cette ligne ne sera pas interprétée.

Cette ligne sera affichée.

Paragraphes et sauts de ligne

AsciiDoc ne nécessite aucune indication spéciale pour les sauts de ligne et les paragraphes. Le texte est rendu tel qu’il a été écrit. Il est toutefois possible de forcer un saut de ligne à l’aide du symbole plus (+). Alternativement, l’attribut [%hardbreaks] peut être ajouté en préambule.


Ceci est la ligne numéro un.
Ceci est la ligne numéro deux.

Et maintenant un autre paragraphe.

Cette ligne sera +
sautée de force.

[%hardbreaks]
Ces lignes seront 
affichées telles quelles.

Mise en forme du texte

Gras, italique, mise en évidence, code

Pour mettre un texte en gras, en italique ou en code, il existe deux possibilités, selon que le texte à formater est isolé ou situé au milieu d’une phrase.

Un mot isolé peut être entouré d’astérisques, de tirets bas, de dièses ou d’accents graves simples.


Ce texte est *gras*.
Ce texte est _italique_.
Ce texte est `code`.
Ce texte est #mis en évidence#.

Si l’on souhaite formater une partie de texte au milieu d’une phrase, cela se fait en utilisant des astérisques, des tirets bas, des dièses ou des accents graves doubles. Si l’on tentait de le faire avec des caractères simples, la règle de formatage serait ignorée.


Les "tt" dans Mi**tt**ag sont en gras.
Les "tt" dans Mi*tt*ag ne sont pas en gras.

Les "tt" dans Mi__tt__ag sont en italique.
Les "tt" dans Mi_tt_ag ne sont pas en italique.

Les "tt" dans Mi``tt``ag sont du code.
Les "tt" dans Mi`tt`ag ne sont pas du code.

Les "tt" dans Mi##tt##ag sont mis en évidence.
Les "tt" dans Mi#tt#ag ne sont pas mis en évidence.

Souligné, barré

Pour souligner ou barrer un texte, on utilise des dièses accompagnés d’un attribut.


Ce texte est [.underline]#souligné#.
Ce texte est [.line-through]#barré#.

Exposant, indice et guillemets intelligents

Grâce aux commandes superscript et subscript, des parties de texte peuvent être mises en exposant ou en indice. Pour cela, le texte est placé entre un accent circonflexe (exposant) ou un tilde (indice).


Ceci est un ~bas~point.
Ceci est un ^haut^point.

Voici le texte AsciiDoc complété avec du contenu pour les chapitres vides (à partir de « Liens »), basé sur la syntaxe officielle AsciiDoc et les bonnes pratiques courantes :

Voici la version révisée de votre documentation AsciiDoc — désormais avec une explication courte et concise pour chaque chapitre, avant les exemples de syntaxe. Le tout reste clair, compréhensible et utile pour les débutants.

Liens

Explication :
AsciiDoc prend en charge à la fois les liens web externes, les renvois internes au document (ancres) et les liens vers des fichiers locaux. La syntaxe est simple et intuitive, idéale pour les documentations devant contenir des liens.

Liens externes

https://www.asciidoc.org[Site web AsciiDoc]

Liens internes (ancres)

[[section1]]
== Première section

Voir aussi <<section1>>.

Liens vers des fichiers

link:manuel.pdf[Télécharger le manuel]

En-tête du document

Explication :
L’en-tête du document contient des métadonnées telles que le titre, l’auteur, la date et des attributs globaux. Il est optionnel, mais recommandé pour les documents structurés, en particulier pour les exports PDF ou livres.

= Titre du document
Nom de l'auteur <auteur@exemple.com>
:doctype: book
:author: Nom de l'auteur
:revdate: 2026-02-09

Table des matières automatique

Explication :
Une table des matières (TOC) est générée automatiquement dès que l’attribut :toc: est défini. Elle peut être placée à gauche, à droite ou à n’importe quel endroit, ce qui est utile pour les documents longs.

:toc: left

= Titre principal

== Chapitre 1
Contenu...

== Chapitre 2
Autre contenu...

Inclusions

Explication :
Avec include::, vous pouvez intégrer des fichiers AsciiDoc externes ou des parties de ceux-ci. Pratique pour les sections réutilisables (pieds de page, notes, chapitres, etc.).

include::chapitre1.adoc[]

include::../partage/notes.adoc[tag=section2]

Listes

Explication :
AsciiDoc prend en charge les listes à puces (*), les listes numérotées (.) et les listes de définitions (::). L’indentation détermine la hiérarchie, ce qui assure une structure simple et claire.

Listes à puces

* Point 1
* Point 2
  * Sous-point

Listes numérotées

. Premier point
. Deuxième point
.. Sous-point

Listes de définitions

Terme::
  Définition du terme.

Images

Explication :
Les images sont intégrées avec image::. Vous pouvez contrôler la taille, le texte alternatif et la mise à l’échelle. Fonctionne en HTML, PDF et EPUB selon le moteur de rendu.

image::logo.png[Logo, 200, 100]

image::diagramme.svg[Diagramme, scaledwidth=50%]

Audio

Explication :
Les fichiers audio (par exemple, des messages vocaux) peuvent être intégrés directement dans le document. Utile pour les tutoriels ou les documentations multimédias.

audio::message-vocal.mp3[Message vocal, autoplay]

Vidéos

Explication :
Les vidéos sont intégrées avec video::. Vous pouvez activer des contrôles comme autoplay, controls ou loop, idéal pour les tutoriels ou présentations.

video::tutoriel.mp4[Tutoriel, width=640, height=360, autoplay, controls]

Macros pour clavier, boutons et menus

Explication :
Avec kbd: et menu:, vous pouvez mettre en évidence les raccourcis clavier et les chemins de menu, particulièrement utile dans les tutoriels ou la documentation logicielle.

Raccourcis clavier

Appuyez sur kbd:[Ctrl+C] pour copier.

Commandes de menu

Allez dans menu:Fichier[Enregistrer sous...].

Code source

Explication :
Les blocs de code avec coloration syntaxique sont introduits avec [source]. Vous pouvez spécifier des langages comme Python, Bash ou HTML, ce qui est utile pour la documentation destinée aux développeurs.

[source,python]
----
def bonjour():
    print("Bonjour le monde")
----

Notes et blocs de texte

Explication :
Avec NOTE:, TIP:, WARNING:, etc., vous pouvez mettre en évidence des informations importantes. Les citations avec ____ sont idéales pour citer des textes ou des sources externes.

Notes

NOTE: Ceci est une information importante.

TIP: Voici comment faire plus rapidement.

Citations

____
« Ceci est une citation. »
— Auteur
____

Tableaux

Explication :
Les tableaux sont définis avec |===. Chaque cellule est séparée par |. Vous pouvez contrôler le nombre de colonnes, les bordures et les en-têtes, parfait pour les comparaisons ou les données.

|===
| Colonne 1 | Colonne 2
| Valeur A  | Valeur B
| Valeur C  | Valeur D
|===

IDs, rôles et options

Explication :
Avec [[id]], vous définissez des ancres pour les liens internes. Avec [.rôle], vous pouvez attribuer des classes CSS. Avec [%option], vous contrôlez le comportement des blocs (par exemple, non numéroté).

IDs

[[chapitre2]]
== Chapitre 2

Rôles

[.note]
Ce texte a un rôle.

Options

[%unnumbered]
== Cette section n'a pas de numéro.

Attributs et caractères spéciaux

Explication :
Les attributs (:nom: valeur) permettent la réutilisation de texte ou de valeurs. Les caractères spéciaux comme + ou \\ doivent parfois être échappés pour ne pas être interprétés comme du formatage.

Attributs

:version: 1.0

La version est {version}.

Caractères spéciaux

+ pour plus, \\ pour barre oblique inverse, &#x27; pour apostrophe.

Bibliographie

Explication :
Une bibliographie peut être créée manuellement ou via bibliography::. Utile pour les documents scientifiques ou référencés.

[bibliography]
== Littérature

- Auteur, Titre, Éditeur, Année

Notes de bas de page

Explication :
Les notes de bas de page sont insérées avec footnote:[Texte] ou [footnote:]. Elles apparaissent à la fin du document ou de la page, idéales pour des informations complémentaires.


Ceci est une phrase avec une note de bas de page.footnote:[Ceci est la note.]

Une autre phrase avec [footnote:2]Note 2[footnote:2].

Conclusion

Avantages

Un grand avantage d’AsciiDoc est certainement son large éventail de fonctionnalités, permettant même la création de documents complexes avec tables des matières et bibliographies. La fonction d’inclusion et la possibilité d’ajouter des commentaires facilitent la gestion de textes longs et de nombreux fichiers ; la collaboration en est également simplifiée. AsciiDoc n’étant pas seulement un langage, mais étant également livré avec une application, il est possible de travailler productivement sans détours inutiles. À part un éditeur de texte pour les fichiers, rien d’autre n’est nécessaire.

Inconvénients

AsciiDoc est loin d’être aussi répandu que Markdown. Des outils productifs comme des applications de notes, des wikis ou des générateurs de sites statiques prennent rarement en charge AsciiDoc, et quand c’est le cas, c’est généralement via des plugins. Ceux qui travaillent beaucoup avec de tels outils ne pourront pas éviter d’utiliser simultanément Markdown et AsciiDoc.

Pour aller plus loin

Littérature

Liens web

Outils pour utiliser AsciiDoc

Éditeurs de texte

Générateurs de sites statiques

Outils de transformation