Introduction à Asciidoctor en Java

1. Introduction

Dans cet article, nous ferons une brève introduction sur l'utilisation d'Asciidoctor avec Java. Nous montrerons comment générer du HTML5 ou un PDF à partir d'un document AsciiDoc.

2. Qu'est-ce qu'AsciiDoc?

AsciiDoc est un format de document texte. Il peut être utilisé pour écrire de la documentation, des livres, des pages Web, des pages de manuel et bien d'autres.

Comme il est très configurable, les documents AsciiDoc peuvent être convertis dans de nombreux autres formats tels que HTML, PDF, pages de manuel, EPUB et autres.

La syntaxe AsciiDoc étant assez basique, elle est devenue très populaire avec un large support dans divers plugins de navigateur, plugins pour langages de programmation et autres outils.

Pour en savoir plus sur l'outil, nous vous suggérons de lire la documentation officielle où vous pouvez trouver de nombreuses ressources utiles pour apprendre la syntaxe et les méthodes appropriées pour exporter votre document AsciiDoc vers d'autres formats.

3. Qu'est-ce qu'Asciidoctor?

Asciidoctor est un processeur de texte pour la conversion de documents AsciiDoc en HTML, PDF et autres formats. Il est écrit en Ruby et conditionné en RubyGem.

Comme mentionné ci-dessus, AsciiDoc est un format très populaire pour l'écriture de documentation, vous pouvez donc facilement trouver Asciidoctor en tant que package standard dans de nombreuses distributions GNU Linux comme Ubuntu, Debian, Fedora et Arch.

Puisque nous voulons utiliser Asciidoctor sur la JVM, nous parlerons d'AsciidoctorJ - qui est Asciidoctor avec Java.

4. Dépendances

Pour inclure le package AsciidoctorJ dans notre application, l' entrée pom.xml suivante est nécessaire:

 org.asciidoctor asciidoctorj 1.5.5   org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

Les dernières versions des bibliothèques peuvent être trouvées ici et ici.

5. API AsciidoctorJ

Le point d'entrée d'AsciidoctorJ est l' interface Java d' Asciidoctor .

Ces méthodes sont:

  • convert - analyse le document AsciiDoc à partir d'une chaîne ou d'un flux et le convertit dans le type de format fourni
  • convertFile - analyse le document AsciiDoc à partir d'un objet File fourni et le convertit dans le type de format fourni
  • convertFiles - identique à la précédente, mais la méthode accepte plusieurs objets File
  • convertDirectory - analyse tous les documents AsciiDoc dans le dossier fourni et les convertit dans le type de format fourni

5.1. Utilisation de l'API dans le code

Pour créer une instance Asciidoctor , vous devez récupérer l'instance à partir de la méthode de fabrique fournie:

import static org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. //some code .. Asciidoctor asciidoctor = create(); 

Avec l'instance récupérée, nous pouvons convertir très facilement le document AsciiDoc:

String output = asciidoctor .convert("Hello _Baeldung_!", new HashMap());

Si nous voulons convertir un document texte à partir du système de fichiers, nous utiliserons la méthode convertFile :

String output = asciidoctor .convertFile(new File("baeldung.adoc"), new HashMap()); 

Pour convertir plusieurs fichiers, la méthode convertFiles accepte l' objet List comme premier paramètre et retourne des tableaux d' objets String .

Plus intéressant est de savoir comment convertir un répertoire entier avec AsciidoctorJ.

Comme mentionné ci-dessus, pour convertir un répertoire entier, nous devons appeler la méthode convertDirectory . Cela scanne le chemin d'accès fourni et recherche tous les fichiers avec les extensions AsciiDoc (.adoc, .ad, .asciidoc, .asc) et les convertit. Pour analyser tous les fichiers, une instance de DirectoryWalker doit être fournie à la méthode.

Actuellement, Asciidoctor fournit deux implémentations intégrées de l'interface mentionnée:

  • AsciiDocDirectoryWalker - convertit tous les fichiers d'un dossier donné et de ses sous-dossiers. Ignore tous les fichiers commençant par «_»
  • GlobDirectoryWalker - convertit tous les fichiers d'un dossier donné suivant une expression glob
String[] result = asciidoctor.convertDirectory( new AsciiDocDirectoryWalker("src/asciidoc"), new HashMap()); 

De plus, nous pouvons appeler la méthode convert avec les interfaces java.io.Reader et java.io.Writer fournies . L' interface du lecteur est utilisée comme source et l' interface Writer est utilisée pour écrire les données converties:

FileReader reader = new FileReader(new File("sample.adoc")); StringWriter writer = new StringWriter(); asciidoctor.convert(reader, writer, options().asMap()); StringBuffer htmlBuffer = writer.getBuffer();

5.2. Génération PDF

Pour générer un fichier PDF à partir d'un document Asciidoc, nous devons spécifier le type de fichier généré dans les options. Si vous regardez un peu plus attentivement les exemples précédents, vous remarquerez que le deuxième paramètre de toute méthode de conversion est un Map - qui représente un objet d'options.

Nous allons définir l'option in_place sur true afin que notre fichier soit automatiquement généré et enregistré dans le système de fichiers:

Map options = options() .inPlace(true) .backend("pdf") .asMap(); String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);

6. Plug-in Maven

Dans la section précédente, nous avons montré comment nous pouvons générer un fichier PDF directement avec votre propre implémentation en Java. Dans cette section, nous montrerons comment générer un fichier PDF lors de la construction de Maven. Des plugins similaires existent pour Gradle et Ant.

Pour activer la génération de PDF pendant la construction, vous devez ajouter cette dépendance à votre pom.xml:

 org.asciidoctor asciidoctor-maven-plugin 1.5.5   org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15   

La dernière version de la dépendance du plugin Maven peut être trouvée ici.

6.1. Usage

Pour utiliser le plugin dans la construction, vous devez le définir dans le pom.xml:

   output-html generate-resources  process-asciidoc    

Étant donné que le plugin ne s'exécute dans aucune phase spécifique, vous devez définir la phase à laquelle vous souhaitez le démarrer.

Comme avec le plugin Asciidoctorj, nous pouvons également utiliser diverses options pour la génération de PDF.

Jetons un coup d'œil aux options de base pendant que vous pouvez trouver d'autres options dans la documentation:

  • sourceDirectory - l'emplacement du répertoire où vous avez des documents Asciidoc
  • outputDirectory - l'emplacement du répertoire dans lequel vous souhaitez stocker les fichiers PDF générés
  • backend - le type de sortie d'Asciidoctor. Pour le jeu de génération PDF pour pdf

Voici un exemple comment définir les options de base dans le plugin:

  src/main/doc target/docs pdf  

Après avoir exécuté la construction, les fichiers PDF se trouvent dans le répertoire de sortie spécifié.

7. Conclusion

Même si AsciiDoc est très facile à utiliser et à comprendre, c'est un outil très puissant pour gérer la documentation et d'autres documents.

Dans cet article, nous avons présenté un moyen simple de générer des fichiers HTML et PDF à partir d'un document AsciiDoc.

Le code peut être trouvé sur over sur GitHub.