AsciiDoc Syntax Quick Reference

AsciiDoc est une norme légère de formatage de texte permettant d’écrire des articles, de la documentation, des livres, des pages web, des diaporamas ou même des pages de man à partir d’un simple texte, enrichi de symboles de présentation. Ce guide est une référence rapide pour la norme de mise en forme de texte AsciiDoc.

Les exemples donnés se concentrent sur le format de sortie HTML de la commande AsciiDoctor. Il est toutefois possible de produire des PDF, des ePub ou encore du DocBook.

La plupart des fonctionnalités estampillées AsciiDoctor only peuvent être obtenues depuis le processeur Python AsciiDoc original en utilisant le fichier de configuration AsciiDoc fourni par le projet AsciiDoctor.

1. Paragraphes

Normal
Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.
Newlines within a paragraph are not displayed.

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.

Line breaks
Rubies are red, +
Topazes are blue.

[%hardbreaks]
Ruby is red.
Java is black.

Rubies are red,
Topazes are blue.

Ruby is red.
Java is black.

Literal
A normal paragraph.

 A paragraph offset by at least one space becomes a literal paragraph.
 All lines in a literal paragraph must be adjacent.

 A literal paragraph is displayed as preformatted text.
 The text is shown in a fixed-width font.
 Spaces and newlines,
 like the ones in this sentence,
 are preserved.

Another normal paragraph.

A normal paragraph.

A paragraph offset by at least one space becomes a literal paragraph.
All lines in a literal paragraph must be adjacent.
A literal paragraph is displayed as preformatted text.
The text is shown in a fixed-width font.
Spaces and newlines,
like the ones in this sentence,
are preserved.

Another normal paragraph.

Admonition
NOTE: An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.

Here are the other built-in admonition types:

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...
An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph.

Here are the other built-in admonition types:

Pro tip…​
Don’t forget…​
Watch out for…​
Ensure that…​
Vous pouvez aussi créer admonition blocks.
Entête de paragraphe
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).

This text will be styled as a lead paragraph (i.e., larger font).

Le style par défaut d’AsciiDoctor donne au premier paragraphe du préambule un style de chapeau.
Plus d’exemple de paragraphes, avertissements et blocs littéraux

Voir ces sections du manuel utilisateur d’AsciiDoctor pour plus d’information et d’exemples :

2. Texte formaté

Gras, italique et police à chasse fixe
bold *constrained* & **un**constrained

italic _constrained_ & __un__constrained

bold italic *_constrained_* & **__un__**constrained

monospace `constrained` & ``un``constrained

monospace bold `*constrained*` & ``**un**``constrained

monospace italic `_constrained_` & ``__un__``constrained

monospace bold italic `*_constrained_*` & ``**__un__**``constrained

bold constrained & unconstrained

italic constrained & unconstrained

bold italic constrained & unconstrained

monospace constrained & unconstrained

monospace bold constrained & unconstrained

monospace italic constrained & unconstrained

monospace bold italic constrained & unconstrained

Marques et style personnalisé
Werewolves are allergic to #cassia cinnamon#.

Did the werewolves read the [.small]#small print#?

Where did all the [.underline]#cores# run off to?

We need [.line-through]#ten# make that twenty VMs.

[.big]##O##nce upon an infinite loop.

Werewolves are allergic to cassia cinnamon.

Did the werewolves read the small print?

Where did all the cores run off to?

We need ten make that twenty VMs.

Once upon an infinite loop.

Indice et exposant
^super^script phrase

~sub~script phrase

superscript phrase

subscript phrase

Guillemets et apostrophes
"`double curved quotes`"

'`single curved quotes`'

Olaf's desk was a mess.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'60s.

“double curved quotes”

‘single curved quotes’

Olaf’s desk was a mess.

All of the werewolves’ desks were a mess.

Olaf had been with the company since the ’60s.

Autres exemples de formatage de texte

Voir ces sections du manuel utilisateur d’AsciiDoctor pour plus d’information et d’exemples.

3. Entêtes de document

Les champs d’entête sont optionnels.
L’entête ne doit pas contenir de ligne blanches et doit être séparée du contenu par au moins une ligne blanche.
Titre seulement
= My Document's Title

My document provides...
Titre et auteur
= My Document's Title
Doc Writer <[email protected]>

My document provides...
AsciiDoctor permet de préciser plusieurs auteurs sur la ligne d’entête d’auteur. Il suffit de les séparer par un point-virgule.
Titre, auteur et révisions
= My Document's Title
Doc Writer <[email protected]>
v1.0, 2014-01-01

My document provides...
Vous ne pouvez pas préciser une révision s’il n’y a pas d’auteur.
Entête de document avec attributs
= My Document's Title
Doc Writer <[email protected]>
v1.0, 2018-04-11
:toc:
:imagesdir: assets/images
:homepage: https://asciidoctor.org

My document provides...

4. Titres de section

Doctype "article"
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

Lorsque vous utiliser le doctype par défaut (article), vous ne pouvez avoir qu’un seul titre de niveau 1 dans le document, et il doit être positionné dans l’entête du document.
Le nombre de signe "égal" devant les titres de section précise leur niveau comme en HTML. Par exemple, Section de niveau 1 devient un titre <h2> en HTML.
doctype "book"
= Document Title (Level 0)

== Section Level 1

=== Section Level 2

==== Section Level 3

===== Section Level 4

====== Section Level 5

= Section Level 0

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5

Section Level 0

Identifiant explicite
[#primitives-nulls]
== Types primitifs et valeurs nulles
Ancres de section et liens (AsciiDoctor seulement)
sectanchors

Quand cet attribut de document est déclaré, une icône apparait devant chaque titre de section portant une ancre vers cette section.

sectlinks

Quand cet attribut est déclaré, les titres de section deviennent des liens. Cela permet au lecteur d’enregistrer un marque-page sur cette section.

Les ancres de titre de section dépendent du style par défaut d’AsciiDoctor pour leur affichage.

5. Fichiers inclus

Portions de document
= Reference Documentation
Lead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
AsciiDoctor n’insert pas de ligne blanches entre deux directives d’inclusion. Il vous revient d’ajouter des lignes blanches après les directives si vous le souhaitez (or lorsqu’une inclusion précède un titre, vous le souhaitez sûrement).
Inclusion depuis une adresse
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
Inclure du contenu depuis une adresse est potentiellement dangereux, et cette fonctionnalité est donc désactivée par défaut en mode sûr (SECURE et au delà). Le mode safe nécessite également l’ajout de l’attribut d’entête :allow-url-read: pour que la directive soit interprêtée.

6. Lignes horizontales et saut de page

Ligne horizontale
'

'

Saut de page
<<<

7. Listes

Liste à puces basique
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

Liste à puces basique (version alternative)
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson
  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

Il doit y avoir une ligne blanche avant et après une liste pour la séparer des autres blocs.
Il est possible de séparer deux listes consécutives en insérant une ligne blanche suivie d’une ligne de commentaire après la première liste. La convention est d’utiliser //- comme ligne de commentaire afin d’indiquer aux autres auteurs qu’il s’agit d’une séparation de listes.
Listes à puce imbriquées
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

Il est possible de changer le type de puce d’une liste à puces via block styles.
Listes ordonnées basiques
. Step 1
. Step 2
. Step 3
  1. Step 1

  2. Step 2

  3. Step 3

Vous pouvez choisir de numéroter les éléments d’une liste, mais les index doivent alors se suivre.
Listes ordonnées imbriquées
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Listes ordonnées, imbrication maximale
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

Pour les listes ordonnées, AsciiDoctor supporte des numeration styles tels que lowergrek (grecque minuscule) et decimal-leading-zero (décimal à zéro apparent).
Listes à cocher
* [*] checked
* [x] also checked
* [ ] not checked
*     normal list item
  • checked

  • also checked

  • not checked

  • normal list item

Étiquetées, en ligne
first term:: definition of first term
second term:: definition of second term
first term

definition of first term

second term

definition of second term

Étiquetées, multi-lignes
first term::
definition of first term
second term::
definition of second term
first term

definition of first term

second term

definition of second term

Questions et réponses
[qanda]
What is Asciidoctor?::
  An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
  1. What is Asciidoctor?

    An implementation of the AsciiDoc processor in Ruby.

  2. What is the answer to the Ultimate Question?

    42

Mélangées
Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

Les listes peuvent être indentées. Les espaces en début de ligne ne sont pas pris en compte.
Contenu complexe au sein d’une liste
* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ gem install asciidoctor

* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language

|AsciiDoc
|Python

|Asciidoctor
|Ruby
|===
  • Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.

    Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

    list continuation

    a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor
  • AsciiDoc lists may contain any complex content.

    Application Language

    AsciiDoc

    Python

    Asciidoctor

    Ruby

8. Liens

Externes
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
Avec des espaces et des caractères spéciaux
link:++https://example.org/?q=[a b]++[URL with special characters]

link:https://example.org/?q=%5Ba%20b%5D[URL with special characters]
Chemin Windows
link:\\server\share\whitepaper.pdf[Whitepaper]
Chemin relatifs
link:index.html[Docs]
Courriel et IRC
[email protected]

mailto:[email protected][Discuss Arquillian]

mailto:[email protected][Subscribe, Subscribe me, I want to join!]

irc://irc.freenode.org/#fedora
Attributs de lien (AsciiDoctor seulement)
http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"]

http://discuss.asciidoctor.org[Discuss Asciidoctor^]

https://example.org["Google, Yahoo, Bing^", role="teal"]
Les attributs de lien (y compris l’objet et le contenu d’un lien courriel mailto:) sont une fonctionnalité d’AsciiDoctor seulement. Pour les activer, il faut déclarer l’attribut d’entête de document :linkattrs:. Lorsqu’ils sont activés, vous devez mettre les textes de lien entre guillemets s’ils contiennent une virgule.
Ancres en plein texte
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

[#bookmark-b]#Inline anchors can be applied to a phrase like this one.#

anchor:bookmark-c[]Use a cross reference to link to this location.

[[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.

Inline anchors make arbitrary content referenceable.

Inline anchors can be applied to a phrase like this one.

Use a cross reference to link to this location.

The xreflabel attribute will be used as link text in the cross-reference link.

Références internes
See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.

See [paragraphs] to learn how to write paragraphs.

Learn how to organize the document into sections.

Références externes vers fichier AsciiDoc (AsciiDoctor seulement)
Refer to <<document-b.adoc#section-b,Section B>> for more information.

See you when you get back from <<document-b#section-b,Section B>>!

Refer to Section B for more information.

See you when you get back from Section B!

9. Images

Les images sont cherchées dans le dossiers déclaré via l’attribut de document imagesdir, qui est nul par défaut. Vous êtes encouragé à déclarer un attribut de document :imagesdir: afin de vous éviter de répéter la partie commune des chemins de vos images.

L’attribut de document imagesdir peut être un chemin absolu, relatif, ou une URL. Lorsque le chemin d’une image est une URL ou un chemin absolu, le préfix :imagesdir: n’est pas inclu.

Blocs
image::sunset.webp[]

image::sunset.webp[Sunset]

.A mountain sunset
[#img-sunset]
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.webp[Sunset,300,200]

image::https://asciidoctor.org/images/octocat.webp[GitHub mascot]
sunset
Sunset
Sunset
Figure 1: A mountain sunset
GitHub mascot
En plein texte
Click image:icons/play.webp[Play, title="Play"] to get the party started.

Click image:icons/pause.webp[title="Pause"] when you need a break.

Click Play to get the party started.

Click pause when you need a break.

Deux fois deux-points collés au mot-clé image (i.e., image::) indiquent d’inclure l’image dans son popre bloc (c’est à dire d’en faire une figure), alors qu’un seul deux-points (donc image:) indique une image en plein texte, traitée comme un caractère. (Toute les macros suivent ce principe, ex : toc::)
Image en plein texte avec rôle de positionnement
image:sunset.webp[Sunset,150,150,role="right"] What a beautiful sunset!

Sunset What a beautiful sunset!

Il y a toute une variété d’attributs disponibles pour le positionnement des images.
Embarquées
= Document Title
:data-uri:
Lorsque l’attribut :data-uri: est déclaré, toutes les images du document — y compris les icônes d’avertissement — sont embarquées sous forme de data URIs.
Au lieu de déclarer l’attribut :data-uri: dans le document, vous pouvez le passer en argument de la ligne de commande via -a data-uri.

10. Vidéos

Blocs
video::video_file.mp4[]

video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
Intégrer une vidéo YouTube
video::rPQoq7ThGAU[youtube]
Intégrer une vidéo Viméo
video::67480300[vimeo]
Vous pouvez contrôler les réglages de la vidéo en utilisant des attributs et leurs options à l’appel de la macro.

11. Code source

Inline (monospace only)
Reference code like `types` or `methods` inline.

Do not pass arbitrary ``Object``s to methods that accept ``String``s!

Reference code like types or methods inline.

Do not pass arbitrary Objects to methods that accept Strings!

En plein texte (littéral)
Output literal monospace text such as `+{backtick}+` by
enclosing the text in pluses, then again in backticks.

Output literal monospace text such as {backtick} by enclosing the text in pluses, then again in backticks.

Ligne littérale complète
 Indent the line one space to insert a code snippet
Indent the line one space to insert a code snippet
Bloc littéral
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
Code source avec titre, sans coloration syntaxique
.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (1.5.6.1)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 1.5.6.1)
----
Gemfile.lock
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (1.5.6.1)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 1.5.6.1)
Code source avec titre et coloration syntaxique
.app.rb
[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
app.rb
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Code source avec renvois
[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body
require 'sinatra' (1)

get '/hi' do (2)
  "Hello World!" (3)
end
1 Library import
2 URL mapping
3 HTTP response body
Bloc de code avec renvois non sélectionnables
----
line of code  // <1>
line of code  # <2>
line of code  ;; <3>
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
line of code  (1)
line of code  (2)
line of code  (3)
1 A callout behind a line comment for C-style languages.
2 A callout behind a line comment for Ruby, Python, Perl, etc.
3 A callout behind a line comment for Clojure.
Bloc de code XML avec renvois non sélectionnables
[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.
<section>
  <title>Section Title</title> (1)
</section>
1 The section title is required.
Bloc de code source intégré depuis un fichier
[source,ruby]
----
include::app.rb[]
----
Bloc de code intégré depuis un fichier présent dans le {sourcedir}
:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----
Retrait de l’indentation originale du code
[source,ruby,indent=0]
----
include::lib/document.rb[lines=5..10]
----
  • Lorsqu'indent vaut 0, l’indentation du code est retirée (les tabulations sont remplacées par des séries de 4 espaces).

  • Lorsqu'indent est supérieur à 0, l’indentation est retirée (comme indiqué ci-dessus) puis remontée au niveau indiqué (en espaces simples).

Bloc de code sans délimiteurs (sans ligne blanche)
[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

Activer la coloration syntaxique

La coloration syntaxique s’active par la déclaration de l’attribut :source-highlighter: en entête du document (ou passé en argument) :

:source-highlighter: pygments

Les options valides sont : coderay, highlightjs, prettify, et pygments.

12. Plus de délimiteurs de bloc

Barre latérale
.AsciiDoc history
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
AsciiDoc history

AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX.

Tout bloc peut avoir un titre, positionné au dessus du bloc. Un titre est une ligne de texte commençant par un point. Le point ne peut pas être suivi d’un espace.
Exemple
.Sample document
====
Here's a sample AsciiDoc document:

[listing]
....
= Title of Document
Doc Writer
:toc:

This guide provides...
....

The document header is useful, but not required.
====
Sample document

Here’s a sample AsciiDoc document:

= Title of Document
Doc Writer
:toc:

This guide provides...

The document header is useful, but not required.

Avertissements
[NOTE]
====
An admonition block may contain complex content.

.A list
- one
- two
- three

Another paragraph.
====

An admonition block may contain complex content.

A list
  • one

  • two

  • three

Another paragraph.

Icônes d’avertissement et de renvoi

AsciiDoctor peut "dessiner" des icônes en utilisant la police de caractères Font Awesome et du CSS.

Pour utiliser cette fonctionnalité, déclarer la valeur icons pour l’attribut de document :font: (à déclarer par la même occasion). AsciiDoctor produira alors les balises HTML permettant de sélectionner les bonnes icônes dans la police Font Awesome pour chaque type d’avertissement.

Les icônes peuvent également être produites à partir de fichier images, voire embarquées dans le code HTML (via le schéma d’URI data).

Les icônes peuvent également être utilisées en plein texte et être stylisées.

Bloc de citation
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____

[quote, Albert Einstein]
A person who never made a mistake never tried anything new.

____
A person who never made a mistake never tried anything new.
____

[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as http://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____

Four score and seven years ago our fathers brought forth on this continent a new nation…​

— Abraham Lincoln
Address delivered at the dedication of the Cemetery at Gettysburg
A person who never made a mistake never tried anything new.
— Albert Einstein

A person who never made a mistake never tried anything new.

If you don’t know where you are going, any road will get you there.

— Charles Lutwidge Dodgson
Mathematician and author, also known as Lewis Carroll
Bloc de citation abrégé (AsciiDoctor seulement)
"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Citations aériennes : la plus belle invention depuis les barrières à bloc de code (AsciiDoctor seulement)
[, James Baldwin]
""
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
""

"" Not everything that is faced can be changed. But nothing can be changed until it is faced. ""

Bloc de contenu intacte
++++
<p>
Content in a passthrough block is passed to the output unprocessed.
That means you can include raw HTML, like this embedded Gist:
</p>

<script src="https://gist.github.com/mojavelinux/5333524.js">
</script>
++++

Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist:

Ouvert
--
An open block can be an anonymous container,
or it can masquerade as any other block.
--

[source]
--
puts "I'm a source block!"
--

An open block can be an anonymous container, or it can masquerade as any other block.

puts "I'm a source block!"
Substitutions sur mesures
:version: 1.5.6.1

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>1.5.6.1</version>
</dependency>

13. Identifiant, rôle et options de bloc

Un rôle se traduit en balisage HTML par un attribut de classe (CSS).
Méthode traditionnelle (verbeuse) d’assignation d’identifiant et de rôle
[[goals]]
[role="incremental"]
* Goal 1
* Goal 2
Méthode raccourcie d’assignation d’identifiant et de rôle (AsciiDoctor seulement)
[#goals.incremental]
* Goal 1
* Goal 2
  • Pour déclarer plusieurs rôles via la méthode raccourcie, il suffit de les séparer par des points.

  • L’ordre des id et role n’a pas d’importance avec la méthode raccourcie.

Méthode traditionelle (verbeuse) d’assignation d’ancre (id) et de rôle
[.e_the_world]][big goal].e the world_
Méthode raccourcie d’assignation d’ancre (id) et de rôle (AsciiDoctor seulement)
[.e_the_world.big.goal].e the world_
Rôle assigné à une portion de texte encadrée par des apostrophes inversées
[.rolename]`monospace text`
Méthode traditionnelle (verbeuse) d’assignation d’option de bloc
[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===
Méthode raccourcie pour l’assignation d’options de bloc (AsciiDoctor seulement)
[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

14. Commentaires

Ligne de commentaire
// A single-line comment.
Les lignes de commentaire peuvent être utilisées pour diviser des éléments, comme deux listes collées sinon.
Bloc de commentaire
////
A multi-line comment.

Notice it's a delimited block.
////

15. Tableau

Tableau avec titre, trois colonnes, une entête et deux lignes de contenu
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3 (1)
(2)
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
Table Title
Name of Column 1 Name of Column 2 Name of Column 3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

1 À moins que l’attribut cols ne soit spécifié, le nombre de colonnes est égal au nombre de séparateur de cellules de la première ligne (non blanche) entre les délimiteurs de bloc.
2 Quand une ligne blanche suit la première ligne non blanche, les cellules de la première ligne deviennent des cellules d’entêtes.
Tableau avec deux colonnes, une entête et deux lignes de contenu
[%header,cols=2*] (1)
|===
|Name of Column 1
|Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

1 La valeur * de l’attribut cols est l’opérateur de répétition. Cela signifie qu’il faut propager les attributs de colonne aux colonnes suivantes. Dans cet exemple, nous propageons le formattage par défaut aux deux colonnes. Quand les cellules d’une entête ne sont pas définies sur une seule ligne, il faut utiliser l’attribut cols pour préciser le nombre de colonnes du tableau, et l’option %header (ou options=header) pour promouvoir la 1ère ligne du tableau aux rang d’entête.
Tableau avec trois colonnes, une entête et deux lignes de contenu
[cols="1,1,2", options="header"] (1)
.Applications
|===
|Name
|Category
|Description

|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance, portability.

|Arquillian
|Testing
|An innovative and highly extensible testing platform.
Empowers developers to easily create real, automated tests.
|===
Applications
Name Category Description

Firefox

Browser

Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance, portability.

Arquillian

Testing

An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests.

1 Dans cet exemple, l’attribut cols a deux fonctions : il annonce que le tableau a trois colonnes, et il précise leur largeur relative.
Tableau avec des colonnes contenant de l’AsciiDoc
[cols="2,2,5a"]
|===
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.

It's designed for:

* standards compliance
* performance
* portability

http://getfirefox.com[Get Firefox]!
|===

Firefox

Browser

Mozilla Firefox is an open-source web browser.

It’s designed for:

  • standards compliance

  • performance

  • portability

Tableau généré à partir de données formattées en CSV (méthode verbeuse)
[%header,format=csv]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

Tableau généré à partir de données formattées en CSV (AsciiDoctor seulement)
,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

Tableau généré à partir d’un fichier CSV (méthode verbeuse)
|===
include::customers.csv[]
|===
Tableau généré à partir de données DSV (AsciiDoctor seulement)
:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===
Artist Track Genre

Robyn

Indestructable

Dance

Tableau avec cellules formattées, alignées et fusionnées
[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

1

2

3

4

5

6

7

8

9

10

16. Macro d’interface graphique

Vous devez déclarer l’attribut :experimental: dans l’entête du document pour activer ces fonctionnalités.
Raccourcis clavier (macro de touche clavier)
|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab

|kbd:[Ctrl+Shift+N]
|New incognito window

|kbd:[\ ]
|Used to escape characters

|kbd:[Ctrl+\]]
|Jump to keyword

|kbd:[Ctrl + +]
|Increase zoom
|===
Shortcut Purpose

F11

Toggle fullscreen

Ctrl+T

Open a new tab

Ctrl+Shift+N

New incognito window

\

Used to escape characters

Ctrl+]

Jump to keyword

Ctrl++

Increase zoom

Sélection de menu (macro pour représenter un menu)
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

To save the file, select File  Save.

Select View  Zoom  Reset to reset the zoom level to the default setting.

Boutons (macro pour représenter des boutons)
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

17. Attributs et substitutions

Déclaration et utilisation d’attributs
:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]
:summary: Asciidoctor is a mature, plain-text document format for \
       writing notes, articles, documentation, books, and more. \
       It's also a text processor & toolchain for translating \
       documents into various output formats (i.e., backends), \
       including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[{startsb}&#10004;{endsb}]

Check out {url-home}[Asciidoctor]!

{summary}

Be sure to read the {link-docs} too!

{checkedbox} That's done!

Check out Asciidoctor!

Asciidoctor is a mature, plain-text document format for writing notes, articles, documentation, books, and more. It’s also a text processor & toolchain for translating documents into various output formats (i.e., backends), including HTML, DocBook, PDF and ePub.

Be sure to read the documentation too!

[✔] That’s done!

Ordre de priorité de déclaration d’attributs (du plus élevé au plus faible)
  • Attributs passés via l’API ou la ligne de commande, et ne se terminant pas par @

  • Attributs définis dans le document

  • Attributs passés via l’API ou la ligne de commande et se terminant par @

  • Valeur par défaut de l’attribut

Pour faire en sorte qu’un attribut passé par l’API ou la ligne de commande ait une priorité moindre que ceux définis dans le document, il faut ajouter un symbole @ à la fin de la valeur de l’attribut en question.
Predefined attributes for character replacements [1][2][3]
Attribute name Replacement text Appearance

blank

nothing

empty

nothing

sp

single space

nbsp

&#160;

 

zwsp[4]

&#8203;

wj[5]

&#8288;

apos

&#39;

'

quot

&#34;

"

lsquo

&#8216;

rsquo

&#8217;

ldquo

&#8220;

rdquo

&#8221;

deg

&#176;

°

plus

&#43;

+

brvbar

&#166;

¦

vbar

|

|

amp

&

&

lt

<

<

gt

>

>

startsb

[

[

endsb

]

]

caret

^

^

asterisk

*

*

tilde

~

~

backslash

\

\

backtick

`

`

two-colons

::

::

two-semicolons

;;

;;

cpp

C++

C++

[1] Some replacements are Unicode characters, whereas others are numeric character references (e.g., &#34;). These character references are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). It’s up to the converter to transform the reference into something the renderer understands (something both the man page and PDF converter handle).

[2] Asciidoctor does not prevent you from reassigning predefined attributes. However, it’s best to treat them as read-only unless the output format requires the use of a different encoding scheme. These attributes are an effective tool for decoupling content and presentation.

[3] Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., &euro; resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named character references—​with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character references (e.g., &#8364;).

[4] The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.

[5] The word joiner (WJ) is a code point in Unicode that prevents a line break at its position.

Environment attributes
Attribute Description Example Value

asciidoctor

Set if the current processor is Asciidoctor.

asciidoctor-version

Asciidoctor version.

2.0.16

backend

The backend used to select and activate the converter that creates the output file. Usually named according to the output format (e.g., html5)

html5

basebackend

The generic backend on which the backend is based. Typically the backend value minus any trailing numbers (e.g., the basebackend for docbook5 is docbook). May also indicate the internal backend employed by the converter (e.g., the basebackend for pdf is html).

html

docdate

Last modified date of the source document.[1,2]

2019-01-04

docdatetime

Last modified date and time of the source document.[1,2]

2019-01-04 19:26:06 UTC

docdir

Full path of the directory that contains the source document. Empty if the safe mode is SERVER or SECURE (to conceal the file’s location).

/home/user/docs

docfile

Full path of the source document. Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file’s location).

/home/user/docs/userguide.adoc

docfilesuffix

File extension of the source document, including the leading period. Introduced in 1.5.6.

.adoc

docname

Root name of the source document (no leading path or file extension).

userguide

doctime

Last modified time of the source document.[1,2]

19:26:06 UTC

doctype

Document type (article, book or manpage).

article

docyear

Year that the document was last modified.[1,2]

2018

embedded

Set if content is being converted to an embeddable document (body only).

filetype

File extension of the output file name (without leading period).

html

htmlsyntax

Syntax used when generating the HTML output (html or xhtml).

html

localdate

Date when the document was converted.[2]

2019-02-17

localdatetime

Date and time when the document was converted.[2]

2019-02-17 19:31:05 UTC

localtime

Time when the document was converted.[2]

19:31:05 UTC

localyear

Year when the document was converted.[2]

2018

outdir

Full path of the output directory. (Cannot be referenced in the content. Only available to the API once the document is converted).

/home/user/docs/dist

outfile

Full path of the output file. (Cannot be referenced in the content. Only available to the API once the document is converted).

/home/user/docs/dist/userguide.html

outfilesuffix

File extension of the output file (starting with a period) as determined by the backend (.html for html, .xml for docbook, etc.). (The value is not updated to match the file extension of the output file when one is specified explicitly). Safe to modify.

.html

safe-mode-level

Numeric value of the safe mode setting. (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).

20

safe-mode-name

Textual value of the safe mode setting.

SERVER

safe-mode-unsafe

Set if the safe mode is UNSAFE.

safe-mode-safe

Set if the safe mode is SAFE.

safe-mode-server

Set if the safe mode is SERVER.

safe-mode-secure

Set if the safe mode is SECURE.

user-home

Full path of the home directory for the current user. Truncated to . if the safe mode is SERVER or SECURE.

/home/user

[1] Only reflects the last modified time of the source document file. It does not consider the last modified time of files which are included.

[2] If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable. This override offers one way to make the conversion reproducible. See https://reproducible-builds.org/specs/source-date-epoch/ for more information about the SOURCE_DATE_EPOCH environment variable. Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., -0600) or UTC if the time zone offset is 0). To force the use of UTC, set the TZ=UTC environment variable when invoking Asciidoctor.

Substitution de nom
none

Disables substitutions

normal

Performs all substitutions except for callouts

verbatim

Replaces special characters and processes callouts

specialchars, specialcharacters

Replaces <, >, and & with their corresponding entities

quotes

Applies text formatting

attributes

Replaces attribute references

replacements

Substitutes textual and character reference replacements

macros

Processes macros

post_replacements

Replaces the line break character (+)

Compteur d’attributs
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description

|PX-{counter:index}
|Description of PX-{index}

|PX-{counter:index}
|Description of PX-{index}
|===
Parts
Part Id Description

PX-1

Description of PX-1

PX-2

Description of PX-2

18. Remplacement de texte

Textual symbol replacements
Name Syntax Unicode Replacement Rendered Notes

Copyright

(C)
&#169;

©

Registered

(R)
&#174;

®

Trademark

(TM)
&#8482;

Em dash

--
&#8212;

 — 

Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces.

When flanked by space characters (e.g., a -- b), the normal spaces are replaced by thin spaces (&#8201;).

Ellipsis

...
&#8230;

…​

Single right arrow

->
&#8594;

Double right arrow

=>
&#8658;

Single left arrow

<-
&#8592;

Double left arrow

<=
&#8656;

Typographic apostrophe

Sam's
Sam&#8217;s

Sam’s

The typewriter apostrophe is replaced with the typographic (aka curly) apostrophe.

Toute entité XML (nommée, numérique ou hexadécimale) est supportée.

19. Texte échappé

Backslash
\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.

\{author} is not resolved to the author name.
The curly brackets around the word are preserved.

`A\--Z` connects A to Z in monospace using two dashes.
The dashes are not replaced by an em dash.

In these cases, the backslash character is automatically removed.

*Stars* is not rendered as bold text. The asterisks around the word are preserved.

{author} is not resolved to the author name. The curly brackets around the word are preserved.

A--Z connects A to Z in monospace using two dashes. The dashes are not replaced by an em dash.

In these cases, the backslash character is automatically removed.

Contenu intact (“délimiteur plus”)
`+Text inside {plus} characters+` is not formatted.
However, special characters like +<+ and +>+ are still escaped.

Text inside {plus} characters is not formatted. However, special characters like < and > are still escaped.

Texte brute (triple plus et macro pass)
+++<u>underline me</u>+++ is underlined.

pass:[<u>underline me</u>] is also underlined.

underline me is underlined.

underline me is also underlined.

20. Table des matières (:toc:)

Déclaration
= AsciiDoc Writer's Guide
Doc Writer <[email protected]>
v1.0, 2013-08-01
:toc:
Table des matières positionnée à droite
= AsciiDoc Writer's Guide
Doc Writer <[email protected]>
v1.0, 2014-08-01
:toc: right
Les titre, niveau et positionnement d’une table des matière peuvent être personnalisés.

21. Bibliographie

Bibliographie avec références internes
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.

[bibliography]
== References

- [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
  From Journeyman to Master. Addison-Wesley. 1999.
- [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
  Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

The Pragmatic Programmer [pp] should be required reading for all developers. To learn all about design patterns, refer to the book by the “Gang of Four” [2].

References

  • [pp] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [2] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

22. Notes de bas de page

Notes de bas de page normale ou réutilisables
A statement.footnote:[Clarification about this statement.]

A bold statement!footnote:disclaimer[Opinions are my own.]

Another bold statement.footnote:disclaimer[]

A statement.[1]

A bold statement![2]

Another bold statement.[2]


1. Clarification about this statement.
2. Opinions are my own.

23. Compatibilité avec Markdown

Les syntaxes compatibles avec Markdown ne sont disponibles qu’avec AsciiDoctor.

Entêtes à la Markdown
# Document Title (Level 0)

## Section Level 1

### Section Level 2

#### Section Level 3

##### Section Level 4

###### Section Level 5

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5
Bloc de code avec coloration syntaxique
```ruby
require 'sinatra'

get '/hi' do
  "Hello World!"
end
```
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Citations à la Markdown
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.

— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Citation avec bloc de contenu à la Markdown
> > What's new?
>
> I've got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.

What’s new?

I’ve got Markdown in my AsciiDoc!

Like what?

  • Blockquotes

  • Headings

  • Fenced code blocks

Is there more?

Yep. AsciiDoc and Markdown share a lot of common syntax already.

Filet horizontal à la Markdown
---

- - -

***

* * *




24. Manuel utilisateur et aide

Pour en apprendre plus sur AsciiDoctor vous pouvez consulter les autres guides et le manuel utilisateur Vous pouvez également rejoindre la liste de diffusion d’AsciiDoctor, où vous pouvez vos questions et laisser des commentaires.