AsciiDoc: Discover and master the syntax for effective documentation
Published on 20 June 2025
Introduction
AsciiDoc is a lightweight markup language, designed for writing structured technical documents, articles, books, or even presentations. It stands out for its readability, syntactic richness, and ability to generate various formats (HTML, PDF, DocBook, etc.). In this article, we will explore the essential syntax of AsciiDoc and suggest tips for quick onboarding.
What is AsciiDoc?
AsciiDoc is a document description language, similar to Markdown but more powerful. It allows efficient structuring of texts, headings, lists, tables, code blocks, and much more. Its versatility makes it a popular choice for documenting open‑source projects, writing books, and publishing on the web.
Why choose AsciiDoc?
-
Readable and intuitive syntax.
-
Native support for complex structures (tables, notes, admonitions, etc.).
-
Multi-format generation (HTML, PDF, ePub, DocBook…).
-
Easy integration with static site generators like JBake or Antora.
-
Advanced customization with the attributes and extensions.
Use case diagram (Use Case)
A use case diagram allows presenting the main interactions between users and the system. Here is a simple example for a documentation system:
@startuml :Utilisateur: --> (Rédiger documentation) :Utilisateur: --> (Générer PDF) :Utilisateur: --> (Publier sur site web) (Rédiger documentation) ..> (Générer PDF) : inclut @enduml
Diagram Mind Map
The mind map (mental map) is ideal for exploring concepts related to AsciiDoc and their relations:
@startmindmap * AsciiDoc ** Syntaxe *** Titres *** Listes *** Blocs de code *** Tableaux ** Extensions *** PlantUML *** MathJax ** Export *** HTML *** PDF *** EPUB @endmindmap
Diagram of Flow (flow)
A flow diagram can be used to describe the process of generating an AsciiDoc document :
@startuml start :Écrire fichier .adoc; :Ajouter images et diagrammes; if (Valider la syntaxe ?) then (oui) :Générer HTML/PDF; :Publier ou partager; else (non) :Corriger erreurs; :back to start; endif stop @enduml
Basic structure of an AsciiDoc file
An AsciiDoc file typically starts with a title, optional attributes, then the structured content. Here is a minimal example:
= Titre Principal
Auteur
2024-09-03
:toc:
:icons: font
Votre contenu commence ici...Fundamental syntax
Titles and sections
AsciiDoc supports multiple heading levels:
= Titre de niveau 1
== Titre de niveau 2
=== Titre de niveau 3
==== Titre de niveau 4Text in bold, italic and monospace
*gras* _italique_ `monospace`Bullet and numbered lists
* Élément 1
* Élément 2
. Premier
. Deuxième
. TroisièmeLinks and images
Lien standard : https://asciidoc.org[AsciiDoc]
Image : image::images/logo.png[AsciiDoc Logo]Code blocks
[source,python]def hello(): print("Hello AsciiDoc !")
tables
|===
| Colonne 1 | Colonne 2
| Valeur A
| Valeur B
| Valeur C
| Valeur D
|===Notes and admonitions
AsciiDoc offers visual information blocks:
NOTE: Ceci est une note importante.
TIP: Conseil utile pour l’utilisateur.
WARNING: Attention à ce point.Use of attributes and variables
Custom attributes allow you to reuse values or configure behaviors:
:project-name: AsciiDoc Explorer
Le projet s’appelle {project-name}.Common use cases
-
Open source project documentation (README, technical guides) - Writing books and ebooks - Automatic generation of static websites (JBake, Antora) - Technical presentations
Best practices
-
Use consistent titles and an automatic table of contents (:toc:). - Prioritize admonitions to draw attention to key points. Structure your files to facilitate maintenance. - Take advantage of annotated code blocks to illustrate examples.
Conclusion
AsciiDoc is a powerful and accessible tool for writing any technical documentation or structured article. Its rich syntax, combined with multi‑format generation, makes it a valuable ally for demanding developers and writers. Try AsciiDoc in your next project and discover the difference!
To go further
-
Official documentation : https://asciidoc.org - Asciidoctor: https://asciidoctor.org - JBake and AsciiDoc: https://jbake.org/docs/2.6.4/#asciidoc_support
Share your experiences and tips in the comments!