Écrire des livres techniques en AsciiDoc

Écrire des livres techniques en AsciiDoc est un excellent choix pour sa simplicité, sa puissance et son intégration avec les outils modernes de documentation et de publication.

  3 minutes à lire  

Écrire des livres techniques en AsciiDoc est un excellent choix pour sa simplicité, sa puissance et son intégration avec les outils modernes de documentation et de publication. Voici les meilleures pratiques et outils pour optimiser ton processus d’écriture et de publication.

Structure et Organisation du Projet

Arborescence recommandée

Organisez votre projet de manière claire et modulaire. Exemple :

mon-livre/
├── manuscript/
│   ├── preface.adoc
│   ├── chapitre1.adoc
│   ├── chapitre2.adoc
│   └── ...
├── images/
│   ├── diagramme1.png
│   └── ...
├── includes/
│   ├── glossaire.adoc
│   └── annexes.adoc
├── styles/
│   └── theme.yml
├── build.sh
└── book.adoc
  • Fichiers modulaires : Un fichier par chapitre ou section majeure pour faciliter la maintenance.
  • Includes : Utilise la directive include::fichier.adoc[] pour assembler le livre à partir de plusieurs fichiers.
  • Ressources externes : Place les images, codes sources et fichiers annexes dans des dossiers dédiés.

Bonnes Pratiques AsciiDoc

Syntaxe et Style

  • Titres hiérarchisés : Utilise =, ==, ===, etc. pour structurer le contenu.

  • Blocs de code : Utilise ````` avec le langage pour la coloration syntaxique :

    [source,python]
-----
def hello():
    print("Hello, AsciiDoc!")
-----

  • Notes et avertissements :

    NOTE: Une information importante.

WARNING: Attention à cette étape !

  • Listes et tableaux : Préfère les tableaux CSV pour les données complexes.

  • Variables : Définis des variables pour les versions, noms de logiciels, etc. :

    :version: 1.0
:logiciel: Python

Ce livre couvre {logiciel} en version {version}.

Gestion des références

  • Liens internes : Utilise <<id-du-titre>> pour les ancres.
  • Bibliographie : Utilise des fichiers .adoc séparés et la directive bibliography::[].

Outils Indispensables

Éditeurs et Plugins

  • Visual Studio Code :
    • Extension AsciiDoc (prévisualisation en direct, autocomplétion).
    • Extension AsciiDoc Preview pour un rendu temps réel.

Génération du Livre

  • Asciidoctor : Outil de référence pour convertir AsciiDoc en HTML, PDF, EPUB.

    • Installation : gem install asciidoctor
    • Génération HTML : asciidoctor book.adoc
    • Génération PDF : asciidoctor-pdf book.adoc (nécessite asciidoctor-pdf).

  • Docker : Pour éviter les problèmes de dépendances, utilise une image Docker avec Asciidoctor préinstallé :

    docker run -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor book.adoc

Automatisation

  • Makefile ou Script Bash : Automatise la génération et la validation.

    # build.sh
asciidoctor book.adoc
asciidoctor-pdf book.adoc

  • GitHub Actions : Intègre la génération dans ton workflow CI/CD pour valider le rendu à chaque commit.

Astuces

  • Diagrammes : Intègre des diagrammes avec PlantUML ou Mermaid directement dans ton AsciiDoc.
  • Tests Automatiques : Utilise asciidoctor-lint pour valider la syntaxe.
  • Thèmes Personnalisés : Crée un fichier theme.yml pour uniformiser le style (couleurs, polices, etc.).

Exemple de Fichier book.adoc

= Titre du Livre
:author: Rudi Bruchez
:doctype: book
:source-highlighter: rouge

include::manuscript/preface.adoc[]

== Premier Chapitre
include::manuscript/chapitre1.adoc[]

== Deuxième Chapitre
include::manuscript/chapitre2.adoc[]

Pour Aller Plus Loin