Einführung in Asciidoctor in Java

1. Einführung

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 fürwriting documentation, books, web pages, man pages and many other. verwendet werden

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

Da die AsciiDoc-Syntax recht einfach ist, ist sie aufgrund der großen Unterstützung für verschiedene Browser-Plugins, Plugins für Programmiersprachen und andere Tools sehr beliebt geworden.

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

3. Was ist Asciidoctor?

Asciidoctor ist eintext processor for converting AsciiDoc documents in HTML, PDF und anderen Formaten. 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 in vielen GNU Linux-Distributionen wie Ubuntu, Debian, Fedora und Arch problemlos als Standardpaket 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, ist der folgendepom.xml-Eintrag erforderlich:


    org.asciidoctor
    asciidoctorj
    1.5.5


    org.asciidoctor
    asciidoctorj-pdf
    1.5.0-alpha.15

Neueste Versionen von Bibliotheken finden Sie unterhere undhere.

5. AsciidoctorJ API

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

Diese Methoden sind:

convert - analysiert das AsciiDoc-Dokument aus einemString oderStream und konvertiert es in den angegebenen Formattyp
convertFile - analysiert das AsciiDoc-Dokument von einem bereitgestelltenFile-Objekt und konvertiert es in den angegebenen Formattyp
convertFiles - wie zuvor, aber die Methode akzeptiert mehrereFile-Objekte
convertDirectory - analysiert alle AsciiDoc-Dokumente im bereitgestellten Ordner und konvertiert sie in den angegebenen Formattyp

5.1. API-Verwendung im Code

Um eineAsciidoctor-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 _example_!", new HashMap());

Wenn Sie ein Textdokument aus dem Dateisystem konvertieren möchten, verwenden wir die MethodeconvertFile:

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

Zum Konvertieren mehrerer Dateien akzeptiert die MethodeconvertFilesdas ObjektListals ersten Parameter und gibt Arrays der ObjekteStringzurück. Interessanter ist, wie man mit AsciidoctorJ ein ganzes Verzeichnis konvertiert.

Wie oben erwähnt, sollten wir zum Konvertieren eines ganzen Verzeichnisses die MethodeconvertDirectoryaufrufen. Dabei wird der angegebene Pfad durchsucht und nach allen Dateien mit den AsciiDoc-Erweiterungen (.adoc, .ad, .asciidoc, .asc) gesucht und konvertiert. Um alle Dateien zu scannen, sollte der Methode eine Instanz vonDirectoryWalker 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());

Außerdem wird diewe can call convert method with provided java.io.Reader and java.io.Writer interfaces.Reader-Schnittstelle als Quelle und dieWriter-Schnittstelle 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

To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. Wenn Sie sich die vorherigen Beispiele etwas genauer ansehen, werden Sie feststellen, dass der zweite Parameter einer KonvertierungsmethodeMap ist - was 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("example.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, wie Sie PDF-Dateien während des Maven-Builds generieren. Simiar plugins exist for Gradle and Ant.

Um die PDF-Generierung während des Builds zu aktivieren, müssen Sie diese Abhängigkeit zu Ihrenpom.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 isthere.

6.1. Verwendungszweck

Um das Plugin im Build zu verwenden, müssen Sie es inpom.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 auch hier verschiedene Optionen für die PDF-Generierung verwendet werden.

Lassen Sie uns einen kurzen Blick auf die grundlegenden Optionen werfen, während Sie andere Optionen indocumentation 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-Generierungssatz für PDF

Dies ist ein Beispiel, wie grundlegende Optionen im Plugin definiert werden:


    
        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 gezeigt, HTML- und PDF-Dateien aus AsciiDoc-Dokumenten zu generieren.

Der Code befindet sich aufover on GitHub.

TOC

Einführung in Asciidoctor in Java