Einführung in Asciidoctor in Java

1. Einleitung

In diesem Artikel geben wir eine kurze Einführung in die Verwendung von Asciidoctor mit Java. Wir zeigen, wie Sie HTML5 oder PDF aus einem AsciiDoc-Dokument generieren.

2. Was ist AsciiDoc?

AsciiDoc ist ein Textdokumentformat. Es kann zum Schreiben von Dokumentationen, Büchern, Webseiten, Manpages und vielen anderen verwendet werden.

Da es sehr konfigurierbar ist, können AsciiDoc-Dokumente in viele andere Formate wie HTML, PDF, Manpages, EPUB und andere konvertiert werden.

Da die AsciiDoc-Syntax recht einfach ist, ist sie mit einer großen Unterstützung in verschiedenen Browser-Plugins, Plugins für Programmiersprachen und anderen Tools sehr beliebt geworden.

Um mehr über das Tool zu erfahren, empfehlen wir Ihnen, die offizielle Dokumentation zu lesen, in der Sie viele nützliche Ressourcen zum Erlernen der richtigen Syntax und Methoden zum Exportieren Ihres AsciiDoc-Dokuments in andere Formate finden.

3. Was ist Asciidoctor?

Asciidoctor ist ein Textprozessor zum Konvertieren von AsciiDoc-Dokumenten in HTML, PDF und andere Formate. Es ist in Ruby geschrieben und als RubyGem verpackt.

Wie oben erwähnt, ist AsciiDoc ein sehr beliebtes Format zum Schreiben von Dokumentation, sodass Sie Asciidoctor als Standardpaket in vielen GNU Linux-Distributionen wie Ubuntu, Debian, Fedora und Arch leicht finden können.

Da wir Asciidoctor in der JVM verwenden möchten, werden wir über AsciidoctorJ sprechen - das ist Asciidoctor mit Java.

4. Abhängigkeiten

Um das AsciidoctorJ-Paket in unsere Anwendung aufzunehmen, wird der folgende pom.xml- Eintrag benötigt:

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

Neueste Versionen von Bibliotheken finden Sie hier und hier.

5. AsciidoctorJ API

Der Einstiegspunkt für AsciidoctorJ ist die Asciidoctor Java-Schnittstelle.

Diese Methoden sind:

  • convert - analysiert ein AsciiDoc-Dokument aus einem String oder Stream und konvertiert es in den angegebenen Formattyp
  • convertFile - parst AsciiDoc Dokument aus einem bereitgestellten Datei - Objekt und wandelt sie in dem vorgesehenen Formattyp
  • convertFiles - wie zuvor, jedoch Methode akzeptiert mehrere Dateiobjekte
  • convertDirectory - analysiert alle AsciiDoc-Dokumente im bereitgestellten Ordner und konvertiert sie in den angegebenen Formattyp

5.1. API-Verwendung im Code

Um eine Asciidoctor- Instanz zu erstellen , müssen Sie die Instanz von der bereitgestellten Factory-Methode abrufen:

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

Mit der abgerufenen Instanz können wir AsciiDoc-Dokumente sehr einfach konvertieren:

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

Wenn wir ein Textdokument aus dem Dateisystem konvertieren möchten, verwenden wir die Methode convertFile :

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

Zum Konvertieren mehrerer Dateien akzeptiert die Methode convertFiles das List- Objekt als ersten Parameter und gibt Arrays von String- Objekten zurück.

Interessanter ist, wie man mit AsciidoctorJ ein ganzes Verzeichnis konvertiert.

Wie oben erwähnt, sollten wir die Methode convertDirectory aufrufen, um ein ganzes Verzeichnis zu konvertieren . Dadurch wird der angegebene Pfad durchsucht und nach allen Dateien mit AsciiDoc-Erweiterungen (.adoc, .ad, .asciidoc, .asc) gesucht und konvertiert. Um alle Dateien zu scannen, sollte der Methode eine Instanz des DirectoryWalker bereitgestellt werden.

Derzeit bietet Asciidoctor zwei integrierte Implementierungen der genannten Schnittstelle:

  • AsciiDocDirectoryWalker - konvertiert alle Dateien eines bestimmten Ordners und seiner Unterordner. Ignoriert alle Dateien, die mit "_" beginnen.
  • GlobDirectoryWalker - Konvertiert alle Dateien eines bestimmten Ordners nach einem Glob-Ausdruck
String[] result = asciidoctor.convertDirectory( new AsciiDocDirectoryWalker("src/asciidoc"), new HashMap()); 

Auch können wir konvertieren Verfahren mit Verfügung gestellt rufen java.io.Reader und java.io.Writer Schnittstellen. Die Reader- Schnittstelle wird als Quelle verwendet, und die Writer- Schnittstelle wird zum Schreiben konvertierter Daten verwendet:

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

5.2. PDF-Generierung

Um eine PDF-Datei aus einem Asciidoc-Dokument zu generieren, müssen Sie den Typ der generierten Datei in den Optionen angeben. Wenn Sie sich die vorherigen Beispiele etwas genauer ansehen, werden Sie feststellen, dass der zweite Parameter einer Konvertierungsmethode eine Map ist, die ein Optionsobjekt darstellt.

Wir setzen die Option in_place auf true, damit unsere Datei automatisch generiert und im Dateisystem gespeichert wird:

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

6. Maven Plugin

Im vorherigen Abschnitt haben wir gezeigt, wie wir PDF-Dateien direkt mit Ihrer eigenen Implementierung in Java generieren können. In diesem Abschnitt zeigen wir Ihnen, wie Sie während des Maven-Builds eine PDF-Datei generieren. Für Gradle und Ant gibt es ähnliche Plugins.

Um die PDF-Generierung während des Builds zu aktivieren, müssen Sie diese Abhängigkeit zu Ihrer pom.xml hinzufügen :

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

Die neueste Version der Maven-Plugin-Abhängigkeit finden Sie hier.

6.1. Verwendung

Um das Plugin im Build zu verwenden, müssen Sie es in der Datei pom.xml definieren:

   output-html generate-resources  process-asciidoc    

Da das Plugin in keiner bestimmten Phase ausgeführt wird, müssen Sie die Phase festlegen, in der Sie es starten möchten.

Wie beim Asciidoctorj-Plugin können wir auch hier verschiedene Optionen für die PDF-Generierung verwenden.

Lassen Sie uns einen kurzen Blick auf die grundlegenden Optionen werfen, während Sie andere Optionen in der Dokumentation finden:

  • sourceDirectory - Der Speicherort des Verzeichnisses, in dem Sie Asciidoc-Dokumente haben
  • outputDirectory - Der Speicherort des Verzeichnisses, in dem Sie generierte PDF-Dateien speichern möchten
  • Backend - der Typ der Ausgabe von Asciidoctor. Für PDF-Generierung auf PDF eingestellt

Dies ist ein Beispiel für die Definition grundlegender Optionen im Plugin:

  src/main/doc target/docs pdf  

Nach dem Ausführen des Builds befinden sich die PDF-Dateien im angegebenen Ausgabeverzeichnis.

7. Fazit

Obwohl AsciiDoc sehr einfach zu bedienen und zu verstehen ist, ist es ein sehr leistungsfähiges Tool zum Verwalten von Dokumentation und anderen Dokumenten.

In diesem Artikel haben wir eine einfache Möglichkeit zum Generieren von HTML- und PDF-Dateien aus AsciiDoc-Dokumenten demonstriert.

Der Code ist auf GitHub zu finden.