Asciidoctor ist ein schneller, Open Source Textverarbeitungs- und Publishing-Toolchain für die Konvertierung von AsciiDoc-Inhalten in HTML 5, DocBook 5, PDF und andere Formate. Asciidoctor ist in Ruby geschrieben und läuft auf allen gängigen Betriebsystemen. Um die Installation zu vereinfachen wird Asciidoctor als Gem auf RubyGems.org verpackt und ist als Paket für gängige Linux-Distributionen und MacOS erhältlich. Asciidoctor kann auch in einer JVM mit AsciidoctorJ oder einer beliebigen Javascript-Umgebung mit Asciidoctor.js ausgeführt werden. Das Asciidoctor-Projekt wird auf GitHub gehostet.
Wir möchten unseren großzügigen Sponsoren danken, ohne deren Unterstützung Asciidoctor nicht möglich wäre. Vielen Dank an die Sponsoren für ihr Engagement zur Verbesserung der technischen Dokumentation! Zusätzliche Mittel werden von unseren Community Backers zur Verfügung gestellt.
Sie können dieses Projekt unterstützen, indem Sie Sponsor bei OpenCollective werden.
Asciidoctor liest Inhalte, die im Klartext geschrieben wurden, wie im Feld links im Bild unten gezeigt, und wandelt Sie in HTML 5 um, wie im rechten Feld dargestellt. Asciidoctor wendet ein Standard-Stylesheet auf das HTML 5-Dokument an, um ein angenehmes Out-of-the-Box-Erlebnis zu bieten.
Asciidoctor liest und analysiert Text, der in der AsciiDoc-Syntax geschrieben wurde, und leitet dann den Parse-Tree durch eine Reihe von eingebauten Konvertern, um HTML 5, DocBook 5 und man-pages zu erzeugen. Sie haben die Möglichkeit, eigene Konverter zu verwenden oder Tilt-gestützte Vorlagen zu laden, um die generierte Ausgabe anzupassen oder zusätzliche Formate zu erzeugen.
Asciidoctor ist ein Ersatz für den Original AsciiDoc Python Prozessor (asciidoc.py).
Die Asciidoctor-Testsuite verfügt über mehr als 2,000 Tests, um die Kompatibilität mit der AsciiDoc-Syntax sicherzustellen.
Neben der klassischen AsciiDoc-Syntax erkennt Asciidoctor zusätzliche Markup- und Formatierungsoptionen, wie z.B. fontbasierte Icons (z.B. icon:fire[]) und UI-Elemente (z.B. button:[Save]).
Asciidoctor bietet auch ein modernes, responsive Theme, das auf Foundation basiert, um die HTML 5-Ausgabe zu gestalten.
Sie können Asciidoctor in einer JVM mit JRuby ausführen. Um die Asciidoctor API direkt aus Java und anderen JVM-Sprachen aufzurufen, verwenden Sie AsciidoctorJ. Es stehen Ihnen auf AsciidoctorJ basierende Plugins zur Verfügung, die den Asciidoctor Prozessor in Apache Maven, Gradle oder Javadoc Builds integrieren.
Asciidoctor läuft auch in JavaScript. Opal wird verwendet, um den Ruby-Source in JavaScript umzukompilieren, um Asciidoctor.js zu erzeugen. Asciidoctor.js ist eine voll funktionsfähige Version von Asciidoctor, die in jeder JavaScript-Umgebung wie z.B. einem Webbrowser oder Node.js funktioniert. Es wird für die AsciiDoc Vorschau-Erweiterungen für Chrome, Atom, Brackets und andere webbasierte Werkzeuge verwendet.
Asciidoctor arbeitet unter Linux, MacOS und Windows und benötigt eine der folgenden Implementierungen von Ruby:
-
CRuby (aka MRI) 2.5 - 3.1
-
JRuby 9.1 - 9.3
-
TruffleRuby (GraalVM)
-
Opal (JavaScript)
|
🔥
|
Wenn Sie eine nicht-englische Windows-Umgebung verwenden, können Sie auf einen chcp 65001 Sobald Sie diese Änderung vorgenommen haben, haben Sie alle Ihre Unicode-Kopfschmerzen hinter sich. Wenn Sie eine IDE wie Eclipse verwenden, stellen Sie sicher, dass Sie dort auch die Kodierung auf UTF-8 setzen. Asciidoctor funktioniert am besten, wenn Sie UTF-8 überall verwenden. |
Asciidoctor kann mit (a) Paketmanagern für gängige Linux-Distributionen, (b) Homebrew für MacOS, (c) dem Befehl gem install (empfohlen für Windows-Benutzer), (d) dem Asciidoctor Docker-Image oder (e) Bundler installiert werden.
Der Vorteil der Verwendung des Paketmanagers Ihres Betriebssystems zur Installation des Gem ist, dass er die Installation von Ruby und der RubyGems-Bibliothek übernimmt, wenn diese Pakete nicht bereits auf Ihrem Rechner installiert sind.
Die vom Paketmanager installierte Version von Asciidoctor entspricht möglicherweise nicht der neuesten Version von Asciidoctor. Konsultieren Sie das Paket-Repository für Ihre Distribution, um herauszufinden, welche Version in der Distribution gepackt ist.
Wenn Sie eine Version von Asciidoctor verwenden möchten, die neuer ist als die, die vom Paketmanager installiert wurde, lesen Sie bitte die Installationsanweisungen.
Um ein Gem auf Alpine Linux zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:
$ sudo apk add asciidoctor
Um ein Gem auf Arch-basierten Distributionen zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:
$ sudo pacman -S asciidoctor
Auf Debian und Debian-basierten Distributionen wie Ubuntu nutzen Sie APT um Asciidoctor zu installieren. Um das Paket zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:
$ sudo apt-get install -y asciidoctor
Sie können Homebrew, den macOS-Paketmanager, verwenden, um Asciidoctor zu installieren. Wenn Sie Homebrew nicht auf Ihrem Computer haben, führen Sie zuerst die Installationsanweisungen unter brew.sh aus. Sobald Homebrew installiert ist, können Sie das Asciidoctor gem installieren. Öffnen Sie ein Terminal und geben Sie folgendes ein:
$ brew install asciidoctor
Homebrew installiert das asciidoctor Gem in ein exklusives Präfix, das unabhängig von den System-Gems ist.
Um Asciidoctor unter Windows zu installieren, gibt es zwei einfache Möglichkeiten.
Wenn Sie bereits chocolatey verwenden, können Sie folgenden Befehl verwenden:
choco install ruby
Danach folgen Sie der Gem Installation.
Oder Sie benutzen den Rubyinstaller, laden Sie das für Ihre Windows Version passende Paket herunter und nach der Installation folgen Sie ebenfalls der Gem Installation.
Bevor Sie Asciidoctor mit gem install installieren, sollten Sie RVM verwenden, um Ruby in Ihrem Home-Verzeichnis zu installieren (z.B. Userspace).
Dann können Sie den Befehl gem sicher verwenden, um den Asciidoctor Gem zu installieren oder zu aktualisieren.
Bei der Verwendung von RVM werden Gems an einem vom System isolierten Ort installiert.
Öffnen Sie ein Terminal und geben Sie folgendes ein:
$ gem install asciidoctor
Wenn Sie eine Vorabversion (z.B. einen Release-Kandidaten) installieren möchten, verwenden Sie:
$ gem install asciidoctor --pre
-
Erstellen Sie ein Gemfile im Stammordner Ihres Projekts (oder im aktuellen Verzeichnis).
-
Fügen Sie den
asciidoctorGem wie folgt zu Ihrem Gemfile hinzu:source 'https://rubygems.org' gem 'asciidoctor' # oder spezifizieren Sie die Version explizit # gem 'asciidoctor', '2.0.20'
-
Speichern Sie das Gemfile
-
Öffnen Sie ein Terminal und installieren Sie das Gem mit:
$ bundle
Um das Gem zu aktualisieren, geben Sie die neue Version im Gemfile an und führen Sie bundle erneut aus.
Die Verwendung von bundle update (ohne Angabe eines Gem) wird nicht empfohlen, da es auch andere Gems aktualisiert, was möglicherweise nicht das gewünschte Ergebnis ist.
Wenn Sie Asciidoctor mit einem Paketmanager installiert haben, ist ihr Betriebssystem wahrscheinlich so konfiguriert, dass es Pakete automatisch aktualisiert. In diesem Fall müssen Sie das Gem nicht manuell aktualisieren.
Wenn Sie Asciidoctor zuvor mit dem Befehl gem installiert haben, müssen Sie Asciidoctor manuell aktualisieren, wenn eine neue Version veröffentlicht wird.
Sie können mit folgendem Befehl aktualisieren:
$ gem install asciidoctor
Wenn Sie eine neue Version des Edelsteins mit gem install installieren, werden mehrere Versionen installiert.
Verwenden Sie den folgenden Befehl, um die alten Versionen zu entfernen:
$ gem cleanup asciidoctor
Wenn der Asciidoctor Gem erfolgreich installiert wurde, ist das asciidoctor Kommandozeilen-Interface (CLI) in Ihrem PATH verfügbar.
Um die Verfügbarkeit zu überprüfen, führen Sie den folgenden Befehl in Ihrem Terminal aus:
$ asciidoctor --version
Sie sollten Informationen über die Asciidoctor-Version und Ihre Ruby-Umgebung im Terminal sehen.
Asciidoctor 2.0.20 [https://asciidoctor.org] Laufzeitumgebung (ruby 3.0.1p4 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
Asciidoctor bietet auch eine API. Die API ist für die Integration mit anderer Ruby-Software wie Rails, Sinatra und GitHub und anderen Sprachen wie Java (über AsciidoctorJ) und JavaScript (über Asciidoctor.js) vorgesehen.
Mit dem Befehl asciidoctor können Sie Asciidoctor von der Kommandozeile (z.B. einem Terminal) aus aufrufen.
Der folgende Befehl konvertiert die Datei README.adoc nach HTML und speichert das Ergebnis in der Datei README.html im gleichen Verzeichnis.
Der Name der erzeugten HTML-Datei wird aus der Quelldatei abgeleitet, indem die Dateierweiterung auf .html geändert wird.
$ asciidoctor README.adoc
Sie können den Asciidoctor-Prozessor steuern, indem Sie verschiedene Flags und Schalter hinzufügen, über die Sie sich mittels folgendem Befehl informieren können:
$ asciidoctor --help
Zum Beispiel, um die Datei in ein anderes Verzeichnis zu schreiben, verwenden Sie:
$ asciidoctor -D output README.adoc
Die asciidoctor man page bietet eine vollständige Referenz der Kommandozeile.
Lesen Sie die folgenden Ressourcen, um mehr über die Verwendung des asciidoctor-Befehls zu erfahren.
Um Asciidoctor in Ihrer Anwendung verwenden zu können, benötigen Sie zunächst das Gem:
require 'asciidoctor'Sie können dann eine AsciiDoc-Quelldatei in eine HTML-Datei konvertieren:
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe|
|
Bei Verwendung von Asciidoctor über die API ist der Standard-Sicherheitsmodus :secure.
Im sicheren Modus sind mehrere Kernfunktionen deaktiviert, darunter die include-Direktive.
Wenn Sie diese Funktionen aktivieren möchten, müssen Sie den Sicherheitsmodus explizit auf :server (empfohlen) oder :safe setzen.
|
Sie können einen AsciiDoc-String auch in ein integrierbares HTML (zum Einfügen in eine HTML-Seite) konvertieren, mit:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safeWenn Sie das komplette HTML-Dokument wünschen, aktivieren Sie die Option head_footer wie folgt:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safeWenn Sie Zugriff auf das analysierte Dokument benötigen, können Sie die Konvertierung in einzelne Schritte aufteilen:
content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convertDenken Sie daran, dass Sie die Ausgabe von Asciidoctor ändern können, wenn Sie sie nicht mögen! Asciidoctor unterstützt benutzerdefinierte Konverter, die die Konvertierung vom geparsten Dokument in die generierte Ausgabe übernehmen können.
Eine einfache Möglichkeit, die Ausgabe stückweise anzupassen, ist die Verwendung des Template-Konverters. Der Template-Konverter ermöglicht es Ihnen, eine von Tilt-gestützte Template-Datei zur Verfügung zu stellen, um die Konvertierung eines beliebigen Knotens im Dokument zu handhaben.
Wie auch immer Sie vorgehen, Sie können die Ausgabe zu 100% kontrollieren. Weitere Informationen zur Verwendung der API oder zur Anpassung der Ausgabe finden Sie im Benutzerhandbuch.
Neue Mitwirkende sind immer willkommen! Wenn Sie Fehler oder Auslassungen im Quellcode, in der Dokumentation oder im Inhalt der Website entdecken, zögern Sie bitte nicht, ein Problem zu melden oder eine Pull Request mit einem Fix zu öffnen.
Hier sind einige Möglichkeiten, wie Sie dazu beitragen können:
-
durch Verwendung von Vorabversionen (Alpha-, Beta- oder Preview-Versionen)
-
durch das Melden von Fehlern
-
durch Vorschläge für neue Funktionen
-
durch das Verfassen oder Bearbeiten von Dokumentationen
-
durch Schreiben von Code mit Tests — Kein Patch ist zu klein.
-
Tippfehler beheben
-
Kommentare hinzufügen
-
inkonsistente Leerzeichen bereinigen
-
Tests schreiben!
-
-
Refactoring von Code
-
durch die Behebung von Problemen
-
durch Überprüfung von Patches
Der Contributing Guide bietet Informationen darüber, wie man Probleme, Feature Requests, Code und Dokumentation für das Asciidoctor Projekt erstellt, gestaltet und einreicht.
Asciidoctor wurde entwickelt, um Ihnen das Schreiben und Veröffentlichen Ihrer Inhalte zu erleichtern. Aber wir können es nicht ohne ihr Feedback machen! Wir ermutigen Sie, Fragen zu stellen und alle Aspekte des Projekts auf der Diskussionsliste, auf Twitter oder im Chatroom zu diskutieren.
- Chat (Zulip)
- Discussionsliste (Nabble)
-
Follow @asciidoctor or search for the #asciidoctor hashtag
Weitere Informationen und Dokumentation zu Asciidoctor finden Sie auf der Website des Projekts.
Die Asciidoctor-Organisation auf GitHub hostet den Quellcode des Projekts, den Issue Tracker und Unterprojekte.
- Source repository (git)
- Issue tracker
- Asciidoctor Organization auf GitHub
Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, und die einzelnen Mitarbeiter von Asciidoctor. Die Nutzung dieser Software wird unter den Bedingungen der MIT-Lizenz gewährt.
Siehe die LIZENZ für den vollen Lizenztext.
Asciidoctor wird von Dan Allen und Sarah White geleitet und hat Beiträge von vielen Personen in Asciidoctors großartiger Gemeinschaft erhalten. Das Projekt wurde 2012 von Ryan Waldron initiiert und basiert auf einem prototyp von Nick Hengeveld.
AsciiDoc wurde von Stuart Rackham gegründet und hat Beiträge von vielen Personen aus der AsciiDoc-Community erhalten.
Eine vollständige Liste der Änderungen in älteren Versionen finden Sie im CHANGELOG.