Version imprimable multipages. Cliquer ici pour imprimer.

Retour à la version par défaut.

Docs-as-Code

1 - Asciidoc

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

2 - Markdown

Markdown est certainement le langage de balisage simple le plus répandu.

Syntaxe

Syntaxe de base

Il s’agit des commandes de base que propose Markdown et qui devraient fondamentalement fonctionner dans tous les outils.

Titres

Pour afficher des titres, un ou plusieurs dièses sont placés devant le titre du niveau correspondant.

# Titre 1

## Titre 2

### Titre 3

#### Titre 4

##### Titre 5

###### Titre 6

Remarque : Il est préférable de toujours insérer une ligne vide avant un titre, car sinon les interprétations peuvent être incorrectes.

Paragraphes/Lignes

Il n’existe pas de réelles notations pour les sauts de ligne et les paragraphes ; le texte est affiché tel qu’écrit. Pour favoriser un saut de ligne, deux espaces peuvent être ajoutés à la fin de la ligne, ou alternativement, la balise HTML <br> peut être utilisée.


Première ligne avec deux espaces à la fin.  
Et maintenant la ligne suivante.

Première ligne avec la balise HTML à la fin.<br>
Et maintenant la ligne suivante.

Mise en forme du texte

Par défaut, Markdown offre la possibilité d’afficher le texte en gras et/ou en italique.

Pour afficher un texte en gras, la partie de texte correspondante est écrite entre deux étoiles ou deux underscores.


J'ai aussi du **texte en gras**.

J'ai aussi du __texte en gras__.

Et voici du **texte en gras** au milieu.

Pour afficher un texte en italique, la partie de texte correspondante est écrite entre une étoile ou un underscore.


J'ai aussi du *texte en italique*.

J'ai aussi du _texte en italique_.

Et voici du *texte en italique* au milieu.

Bien sûr, il est aussi possible de les combiner :

Pour afficher un texte en gras et en italique, la partie de texte correspondante est écrite entre trois étoiles ou trois underscores.


J'ai aussi du ***texte en gras et en italique***.

J'ai aussi du ___texte en gras et en italique___.

Et voici du ***texte en gras et en italique*** au milieu.

Citations (Blockquotes)

Pour citer un texte sous forme de bloc, il suffit de placer un signe « supérieur à » devant la ligne.


> Ce texte se trouve dans une citation.

Si la citation doit s’étendre sur plusieurs lignes, le signe « supérieur à » doit être placé au début de chaque ligne (y compris les lignes vides).


> Ce texte représente la première ligne de la citation.
> 
> Et voici la ligne suivante.

Les citations peuvent également être imbriquées ; dans ce cas, un signe « supérieur à » supplémentaire est ajouté pour le niveau ou l’indentation suivante.


> Ce texte se trouve dans une citation.
> 
>> Ce texte est imbriqué.

Listes

Les listes sont tout aussi simples et sont écrites directement dans le texte. Si la liste passe à un autre niveau, cela est permis par une indentation (4 espaces ou 1 tabulation).

Liste ordonnée

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.


1. Premier élément
2. Deuxième élément
3. Troisième élément
    1. première indentation
    2. deuxième indentation
4. Quatrième élément
Liste non ordonnée

Les listes non ordonnées sont générées en plaçant simplement un tiret devant la ligne.


- Premier élément
- Deuxième élément
- Troisième élément
    - première indentation
    - deuxième indentation
- Quatrième élément

Liens et images

Pour afficher un lien, le texte du lien est placé entre crochets, suivi de l’URL entre parenthèses.

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.


Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr).

Un titre peut également être ajouté au lien sous forme d’infobulle.


Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr "Le moteur de recherche suisse").

Comme forme abrégée, une URL peut aussi simplement être écrite entre crochets angulaires.


Mon moteur de recherche préféré est <https://swisscows.com/fr>.

Syntaxe étendue

Tableaux

Les tableaux sont définis à l’aide de barres verticales (|) et de tirets (-). La première ligne contient les en-têtes de colonnes, la deuxième ligne définit l’alignement (facultatif).

| Aligné à gauche | Centré        | Aligné à droite |
| :-------------- | :-----------: | --------------: |
| Cellule 1       | Cellule 2     | Cellule 3       |
| Cellule 4       | Cellule 5     | Cellule 6       |

Remarque : Le nombre de tirets dans la ligne de séparation est arbitraire ; seul le : pour l’alignement est important.

Blocs de code

Pour du code sur plusieurs lignes, un bloc de code est créé avec trois accents graves (```) ou avec quatre espaces par ligne. Facultativement, le langage peut être spécifié pour activer la coloration syntaxique.

```python
def hello():
    print("Bonjour le monde !")


---

#### Notes de bas de page

Les notes de bas de page sont insérées dans le texte avec `[^identifiant]` et définies à la fin du fichier avec `[^identifiant]:`.

```markdown
Voici un texte avec une note de bas de page.[^1]

[^1]: Ceci est l'explication de la note de bas de page.

Remarque : Tous les analyseurs Markdown ne prennent pas en charge les notes de bas de page – par exemple, Hugo nécessite goldmark avec l’option activée.

ID pour les titres

Les titres peuvent être dotés d’un ID pour y accéder directement (par exemple, pour les tables des matières ou les liens d’ancrage).

## Titre avec ID {#mon-id}

[Lien vers le titre](#mon-id)

Remarque : Dans Hugo, enableInlineShortcodes = true doit être activé dans la configuration.

Listes de tâches

Les listes de tâches (checklists) sont créées avec - [ ] pour les éléments non cochés et - [x] pour les éléments cochés.

- [x] Tâche terminée
- [ ] À faire
- [ ] À faire plus tard

Remarque : Souvent utilisé dans GitHub, GitLab ou des applications de notes comme Obsidian.

Texte barré

Le texte barré est entouré de deux tildes (~~).

Ce texte est ~~barré~~.

Émojis

Les émojis peuvent être insérés directement (par exemple, 😊) ou avec des codes courts comme :smile: (selon l’analyseur).

Je suis de bonne humeur aujourd'hui 😊

Remarque : Dans Hugo, les émojis doivent être explicitement activés (enableEmoji = true).

Mise en évidence du texte

Certains analyseurs (par exemple, Hugo avec Goldmark) prennent en charge la mise en évidence avec == :

Ce texte est ==mis en évidence==.

Remarque : Non standardisé – ne fonctionne pas partout.

Indices/Exposants

Les indices (H₂O) et les exposants (x²) sont représentés respectivement avec ~ et ^ – mais uniquement dans certaines extensions comme Pandoc ou Hugo avec un analyseur spécial.

L'eau est H~2~O.  
x^2^ est x au carré.

Remarque : Ne fait pas partie de la norme CommonMark – Fonctionne, par exemple, dans Hugo avec goldmark et l’option activée.

Utilisation

Markdown ne représente pas un système en soi, mais se contente d’une syntaxe ouverte et librement disponible. On pourrait comparer Markdown à un langage de script intégrable. C’est certainement aussi la raison pour laquelle tant de systèmes prennent en charge Markdown et que le langage est ainsi si polyvalent.

Systèmes Wiki

Les systèmes Wiki tels que Mediawiki (sur lequel Wikipédia est basé), dokuWiki, ou les fonctions wiki intégrées comme celles de GitHub ou GitLab utilisent standardement Markdown pour la gestion du contenu.

Les wikis sont avant tout là pour présenter du contenu, dans le domaine Git, la documentation du logiciel proposé. Grâce à la syntaxe simple, ceux-ci peuvent également être créés et gérés par des non-spécialistes.

Notes

Les applications de notes largement disponibles (ou parfois aussi appelées wikis de bureau) reposent également sur Markdown pour la gestion du contenu. Souvent, un éditeur WYSIWYG intégré est fourni, mais il utilise Markdown en arrière-plan. Il est également généralement possible de passer au texte source et d’éditer directement. Des exemples incluent Zim, Zettlr, QOwnNotes, et Logseq dans le domaine open source, ou des variantes populaires comme Evernote, Obsidian, ou Joplin.

Sites Web

Dans le domaine des sites Web, Markdown apparaît de deux manières. D’une part, les systèmes de gestion de contenu connus (comme WordPress et Drupal) offrent souvent des plugins/modules pour publier du contenu en Markdown. Mais outre les CMS, il existe aussi des SSG, appelés générateurs de sites statiques, comme Hugo ou Jekyll. De plus, il existe des systèmes similaires spécialisés dans la documentation technique comme MKDocs, Sphinx, ou Docusaurus. Ici aussi, tout le contenu est créé en Markdown puis converti en sites web statiques à l’aide d’un préprocesseur, qui peuvent ensuite être publiés.

Présentations/Cours

Outre les sites web, des présentations peuvent également être créées avec Markdown. Cependant, il ne s’agit pas de présentations PowerPoint, mais celles-ci sont dynamiquement converties en éléments web à l’aide de préprocesseurs. Des exemples incluent Marp, remarkJS, ou Cleaver. Spécifiquement pour les cours en ligne, l’extension Markdown LiaScript est appropriée.

Documents

Il manque certainement à Markdown certaines fonctionnalités qu’un traitement de texte comme MS Word ou LibreOffice Writer peut offrir, mais il est parfaitement suffisant pour des documents simples tels que des lettres.

Conclusion

Avantages

Markdown a une syntaxe simple et claire et est donc facile à apprendre. Les documents Markdown ont également l’avantage d’être facilement lisibles même en texte source. Ils sont donc à la fois lisibles par machine et par l’homme. Ce dernier grâce à la syntaxe simple et directe sans surcharge. La large diffusion de Markdown et son intégration dans tant d’outils parlent également d’eux-mêmes.

Inconvénients

Outre les avantages clairs, il y a malheureusement aussi des aspects négatifs à signaler concernant Markdown.

Markdown convient très bien pour des articles et des notes qui ne sont pas structurés de manière trop complexe. Si l’on souhaite créer davantage, par exemple des documents grands et complexes, tels que des livres entiers, des fonctions utiles comme une table des matières ou la possibilité d’imbriquer des fichiers en utilisant “Include” manquent.

Bien qu’il existe une norme Markdown avec CommonMark, la forte diffusion a néanmoins conduit à de nombreux “dialectes”, car de nombreux outils étendent la syntaxe standard avec leurs propres commandes. Par conséquent, les documents Markdown provenant de différents systèmes ne sont pas nécessairement compatibles entre eux.

Informations complémentaires

Liens Web

Outils pour utiliser Markdown

Wikis de bureau

Éditeurs de texte

Générateurs de sites statiques

Outils de transformation