Asciidoctor ist ein schneller, Open Source Textverarbeitungs- und Publishing-Toolchain für die Konvertierung von AsciiDoc-Inhalten in HTML5, DocBook, 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.

Dieses Dokument ist auch in folgenden Sprachen erhältlich:
汉语 | English | Français | 日本語

Wichtige Dokumentation

Sponsoren

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!

     

Unsere Change Makers, Okta und OpenDevise, sowie unsere Strategiesponsoren Khronos Group und Linda Roberts finanzieren Asciidoctor maßgeblich. 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.

Das große Ganze

Asciidoctor liest Inhalte, die im Klartext geschrieben wurden, wie im Feld links im Bild unten gezeigt, und wandelt Sie in HTML5 um, wie im rechten Feld dargestellt. Asciidoctor wendet ein Standard-Stylesheet auf das HTML5-Dokument an, um ein angenehmes Out-of-the-Box-Erlebnis zu bieten.

image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]

AsciiDoc Verarbeitung

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 HTML5, 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 HTML5-Ausgabe zu gestalten.

Wo Ruby hingeht, folgt Asciidoctor

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.

Anforderungen

Asciidoctor arbeitet unter Linux, MacOS und Windows und benötigt eine der folgenden Implementierungen von Ruby:

  • Ruby (MRI/CRuby 1.8.7 - 2.5)

  • JRuby (1.7 in Ruby 1.8 und 1.9 modes, 9000)

  • Rubinius 2.2.x

  • Opal (JavaScript)

Caution

Wenn Sie eine nicht-englische Windows-Umgebung verwenden, können Sie auf einen Encoding::UndefinedConversionError stoßen, wenn Sie Asciidoctor aufrufen. Um dieses Problem zu beheben, empfehlen wir, die aktive Codepage in Ihrer Konsole auf UTF-8 umzustellen:

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.

Installation

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.

(a) Linux Paketmanager

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.

apk (Alpine Linux)

Um ein Gem auf Alpine Linux zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:

$ sudo apk add asciidoctor

pacman (Arch Linux)

Um ein Gem auf Arch-basierten Distributionen zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:

$ sudo pacman -S asciidoctor

APT

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

DNF

Auf RPM-basierten Linux-Distributionen, wie Fedora, CentOS und RHEL, nutzen Sie den DNF Paketmanager um Asciidoctor zu installieren. Um das Paket zu installieren, öffnen Sie ein Terminal und geben Sie folgendes ein:

$ sudo dnf install -y asciidoctor

(b) Homebrew (macOS)

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.

(c) Windows

Um Asciidoctor unter Windows zu installieren, gibt es zwei einfache Möglichkeiten.

Chocolatey

Wenn Sie bereits chocolatey verwenden, können Sie folgenden Befehl verwenden:

choco install ruby

Danach folgen Sie der Gem Installation.

Rubyinstaller

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.

(d) gem install

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

(e) Docker

Siehe Installing Asciidoctor using Docker.

(f) Bundler

  1. Erstellen Sie ein Gemfile im Stammordner Ihres Projekts (oder im aktuellen Verzeichnis).

  2. Fügen Sie den asciidoctor Gem wie folgt zu Ihrem Gemfile hinzu:

    source 'https://rubygems.org'
gem 'asciidoctor'
# oder spezifizieren Sie die Version explizit
# gem 'asciidoctor', '1.5.8'

  3. Speichern Sie das Gemfile

  4. Ö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.

Upgrade

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.

apk (Alpine Linux)

Um das Gem zu aktualisieren, nutzen Sie:

$ sudo apk add -u asciidoctor

APT

Um das Gem zu aktualisieren, nutzen Sie:

$ sudo apt-get upgrade -y asciidoctor

DNF

Um das Gem zu aktualisieren, nutzen Sie:

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

Um das Gem zu aktualisieren, nutzen Sie:

$ brew update
$ brew upgrade asciidoctor

gem install

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

Verwendung

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 1.5.7 [https://asciidoctor.org]
Laufzeitumgebung (ruby 2.5.1p57 [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.

Kommandozeile

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.

Ruby API

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
Warning
 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: :safe

Wenn 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: :safe

Wenn 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.convert

Denken 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.

Mitwirken

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.

Hilfe finden

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.

Discussionsliste (Nabble)

http://discuss.asciidoctor.org

Twitter

#asciidoctor hashtag or @asciidoctor mention

Die Asciidoctor-Organisation auf GitHub hostet den Quellcode des Projekts, den Issue Tracker und Unterprojekte.

Source repository (git)

https://github.com/asciidoctor/asciidoctor

Issue tracker

https://github.com/asciidoctor/asciidoctor/issues

Asciidoctor Organization auf GitHub

https://github.com/asciidoctor

Lizenz

Copyright © 2012-2018 Dan Allen, Sarah White 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.

Authoren

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 https://github.com/erebor[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.

Changelog

1.5.7.1 (2018-05-10) - @mojavelinux

Fixes

  • fix regression where block attributes where being inherited by sibling blocks in a complex list item (#2771)

  • don’t apply lead styling to first paragraph in nested document (AsciiDoc table cell) if role is present (#2624)

Build / Infrastructure

  • drop obsolete logic in rake build (@aerostitch)

  • allow lib dir to be overridden for tests using an environment variable (PR #2758) (@aerostitch)

  • load asciidoctor/version from LOAD_PATH in gemspec if not found locally (PR #2760) (@aerostitch)

1.5.7 (2018-05-02) - @mojavelinux

Enhancements

  • BREAKING: drop XML tags, character refs, and non-word characters (except hyphen, dot, and space) when auto-generating section IDs (#794)

    • hyphen, dot, and space are replaced with value of idseparator, if set; otherwise, spaces are dropped

  • allow attribute names to contain any word character defined by Unicode (#2376, PR #2393)

  • do not recognize attribute entry line if name contains a colon (PR #2377)

  • route all processor messages through a logger instead of using Kernel#warn (#44, PR #2660)

  • add MemoryLogger for capturing messages sent to logger into memory (#44, PR #2660)

  • add NullLogger to prevent messages from being logged (#44, PR #2660)

  • log message containing source location / cursor as an object; provides more context (#44, PR #2660)

  • pass cursor for include file to :include_location key in message context (PR #2729)

  • add :logger option to API to set logger instance (#44, PR #2660)

  • add --failure-level=LEVEL option to CLI to force non-zero exit code if specified logging level is reached (#2003, PR #2674)

  • parse text of xref macro as attributes if attribute signature found (equal sign) (#2381)

  • allow xrefstyle to be specified per xref by assigning the xrefstyle attribute on the xref macro (#2365)

  • recognize target with .adoc extension in xref macro as an interdocument xref

  • resolve nested includes in remote documents relative to URI (#2506, PR #2511)

  • allow relfilesuffix attribute to control file extension used for interdoc xrefs (#1273)

  • support !name@ (preferred), !name=@, name!@, and name!=@ syntax to soft unset attribute from API or CLI (#642, PR #2649)

  • allow modifier to be placed at end of name to soft set an attribute (e.g., icons@=font) (#642, PR #2649)

  • interpret false attribute value defined using API as a soft unset (#642, PR #2649)

  • number parts if partnums attribute is set (#2298)

  • allow footnote macro to define or reference footnote reference (footnoteref macro now deprecated) (#2347, PR #2362)

  • allow custom converter to be used with custom templates; converter must declare that it supports templates (#2619)

  • allow manpage path for manpage help topic to be specified using ASCIIDOCTOR_MANPAGE_PATH environment variable (PR #2653) (@aerostitch)

  • if manpage cannot be found in default path inside gem, use man -w asciidoctor to resolve installed path (PR #2653)

  • uncompress contents of manpage for manpage help topic if path ends with .gz (PR #2653) (@aerostitch)

  • define source and manual refmiscinfo entries in manpage output if manual and source attributes are defined (PR #2636) (@tiwai)

  • add syntax for adding hard line breaks in block AsciiMath equations (#2497, PR #2579) (@dimztimz)

  • add positioning option to sectanchors attribute (sectanchors=before or sectanchors=after) (#2485, PR #2486)

  • allow table striping to be configured using stripes attribute (even, odd, all, or none) or stripes roles on table (#1365, PR #2588)

  • recognize ends as an alias to topbot for configuring the table frame

  • add rel=nofollow property to links (text or image) when nofollow option is set (#2605, PR #2692)

  • populate Document#source_location when sourcemap option is enabled (#2478, PR #2488)

  • populate source_location property on list items when sourcemap option is set on document (PR #2069) (@mogztter)

  • populate Table::Cell#source_location when sourcemap option is enabled (#2705)

  • allow local include to be flagged as optional by setting optional option (#2389, PR #2413)

  • allow block title to begin with a period (#2358, PR #2359)

  • catalog inline anchor at start of list items in ordered and unordered lists, description list terms, and table cells (#2257)

  • register document in catalog if id is set; assign reftext to document attributes if specified in a block attribute line (#2301, PR #2428)

  • allow automatic width to be applied to individual columns in a table using the special value ~ (#1844)

  • use the quote element in DocBook converter to represent smart quotes (#2272, PR #2356) (@bk2204)

  • parse and pass all manpage names to output document master (i.e., shadow man pages) (#1811, #2543, PR #2414)

  • parse credit line of shorthand quote block as block attributes; apply normal subs to credit line in shorthand quote blocks (#1667, PR #2452)

  • populate copyright element in DocBook output from value of copyright attribute (#2728)

  • preserve directories if source dir and destination dir are set (#1394, PR #2421)

  • allow linkcss to be unset from API or CLI when safe mode is secure

  • convert quote to epigraph element in DocBook output if block has epigraph role (#1195, PR #2664) (@bk2204)

  • number special sections in addition to regular sections when sectnums=all (#661, PR #2463)

  • upgrade to Font Awesome 4.7.0 (#2569)

  • upgrade to MathJax 4.7.4

Bug fixes

  • set :to_dir option value correctly when output file is specified (#2382)

  • preserve leading indentation in contents of AsciiDoc table cell if contents starts with a newline (#2712)

  • the shorthand syntax on the style to set block attributes (id, roles, options) no longer resets block style (#2174)

  • match include tags anywhere on line as long as offset by word boundary on left and space or newline on right (#2369, PR #2683)

  • warn if an include tag specified in the include directive is unclosed in the included file (#2361, PR #2696)

  • use correct parse mode when parsing blocks attached to list item (#1926)

  • fix typo in gemspec that removed README and CONTRIBUTING files from the generated gem (PR #2650) (@aerostitch)

  • preserve id, role, title, and reftext on open block when converting to DocBook; wrap in <para> or <formalpara> (#2276)

  • don’t turn bare URI scheme (no host) into a link (#2609, PR #2611)

  • don’t convert inter-document xref to internal anchor unless entire target file is included into current file (#2200)

  • fix em dash replacement in manpage converter (#2604, PR #2607)

  • don’t output e-mail address twice when replacing bare e-mail address in manpage output (#2654, PR #2665)

  • use alternate macro for monospaced text in manpage output to not conflict w/ AsciiDoc macros (#2751)

  • enforce that absolute start path passed to PathResolver#system_path is inside of jail path (#2642, PR #2644)

  • fix behavior of PathResolver#descends_from? when base path equals / (#2642, PR #2644)

  • automatically recover if start path passed to PathResolver#system_path is outside of jail path (#2642, PR #2644)

  • re-enable left justification after invoking tmac URL macro (#2400, PR #2409)

  • don’t report warning about same level 0 section multiple times (#2572)

  • record timings when calling convert and write on Document (#2574, PR #2575)

  • duplicate header attributes when restoring; allows header attributes to be restored an arbitrary number of times (#2567, PR #2570)

  • propagate :catalog_assets option to nested document (#2564, PR #2565)

  • preserve newlines in quoted CSV data (#2041)

  • allow opening quote around quoted CSV field to be on a line by itself

  • output table footer after body rows (#2556, PR #2566) (@PauloFrancaLacerda)

  • move @page outside of @media print in default stylesheet (#2531, PR #2532)

  • don’t throw exception if text of dd node is nil (#2529, PR #2530)

  • don’t double escape ampersand in manpage output (#2525) (@dimztimz)

  • fix crash when author_1 attribute is assigned directly (#2481, PR #2487)

  • fix CSS for highlighted source block inside colist (#2474, PR #2490)

  • don’t append file extension to data uri of admonition icon (#2465, PR #2466)

  • fix race condition in Helpers.mkdir_p (#2457, PR #2458)

  • correctly process nested passthrough inside unconstrained monospaced (#2442, PR #2443)

  • add test to ensure ampersand in author line is not double escaped (#2439, PR #2440)

  • prevent footnote ID from clashing with auto-generated footnote IDs (#2019)

  • fix alignment of icons in footnote (#2415, PR #2416)

  • add graceful fallback if pygments.rb fails to return a value (#2341, PR #2342)

  • escape specialchars in source if pygments fails to highlight (#2341)

  • do not recognize attribute entry line if name contains colon (PR #2377)

  • allow flow indexterm to be enclosed in round brackets (#2363, PR #2364)

  • set outfilesuffix to match file extension of output file (#2258, PR #2367)

  • add block title to dlist in manpage output (#1611, PR #2434)

  • scale text to 80% in print styles (#1484, PR #2576)

  • fix alignment of abstract title when using default stylesheet (PR #2732)

  • only set nowrap style on table caption for auto-width table (#2392)

  • output non-breaking space for man manual if absent in DocBook output (PR #2636)

  • don’t crash if stem type is not recognized (instead, fallback to asciimath)

Improvements / Refactoring

  • BREAKING: rename table spread role to stretch (#2589, PR #2591)

  • use cursor marks to track lines more accurately; record cursor at the start of each block, list item, or table cell (PR #2701, PR #2547) (@seikichi)

  • log a warning message if an unterminated delimited block is detected (#1133, PR #2612)

  • log a warning when nested section is found inside special section that doesn’t support nested sections (#2433, PR #2672)

  • read files in binary mode to disable automatic endline coercion (then explicitly coerce to UTF-8) (PR #2583, PR #2694)

  • resolve / expand parent references in start path passed to PathResolver#system_path (#2642, PR #2644)

  • update PathResolver#expand_path to resolve parent references (#2642, PR #2644)

  • allow start path passed to PathResolver#system_path to be outside jail if target brings resolved path back inside jail (#2642, PR #2644)

  • don’t run File.expand_path on Dir.pwd (assume Dir.pwd is absolute) (#2642, PR #2644)

  • posixify working_dir passed to PathResolver constructor if absolute (#2642, PR #2644)

  • optimize detection for footnote* and indexterm* macros (#2347, PR #2362)

  • log a warning if a footnote reference cannot be resolved (#2669)

  • set logger level to DEBUG when verbose is enabled

  • coerce value of :template_dirs option to an Array (PR #2621)

  • make block roles specified using shorthand syntax additive (#2174)

  • allow paragraph to masquerade as open block (PR #2412)

  • move callouts into document catalog (PR #2394)

  • document ID defined in block attribute line takes precedence over ID defined inside document title line

  • don’t look for link and window attributes on document when resolving these attributes for an image

  • when linkattrs is set, only parse attributes in link macro if equals is present

  • skip line comments in name section of manpage (#2584, PR #2585)

  • always activate extension registry passed to processor (PR #2379)

  • skip extension registry activation if no groups are registered (PR #2373)

  • don’t apply lead styling to first paragraph if role is present (#2624, PR #2625)

  • raise clearer exception when extension class cannot be resolved (#2622, PR #2623)

  • add methods to read results from timings (#2578, PR #2580)

  • collapse bottom margin of last block in AsciiDoc table cell (#2568, PR #2593)

  • set authorcount to 0 if there are no authors (#2519, PR #2520)

  • validate fragment of interdoc xref that resolves to current doc (#2448, PR #2449)

  • put id attribute on tag around phrase instead of preceding anchor (#2445, PR #2446)

  • add .plist extension to XML circumfix comment family (#2430, PR #2431) (@akosma)

  • alias Document#title method to no args Document#doctitle method (#2429, PR #2432)

  • upgrade missing or unreadable include file to an error (#2424, PR #2426)

  • add compliance setting to disable natural cross references (#2405, PR #2460)

  • make hash in inter-document xref target optional if target has extension (#2404, PR #2406)

  • add CSS class to part that matches role (#2401, PR #2402)

  • add fit-content class to auto-width table (#2392)

  • automatically assign parent reference when adding node to parent (#2398, PR #2403)

  • leave inline anchor in section title as is if section has ID (#2243, PR #2427)

  • align and improve error message about invalid use of partintro between HTML5 and DocBook converters

  • rephrase warning when level 0 sections are found and the doctype is not book

  • report correct line number when duplicate bibliography anchor is found

  • only warn if thread_safe gem is missing when using built-in template cache

  • rename enumerate_section to assign_numeral; update API docs

  • drop deprecated compact option from CLI; remove from manpage

  • use more robust mechanism for lazy loading the asciimath gem

  • use consistent phrase to indicate the processor is automatically recovering from a problem

  • change Reader#skip_comment_lines to not return skipped lines

  • add styles to default stylesheet for display on Kindle (kf8) devices (PR #2475)

  • purge render method from test suite (except to verify alias)

Documentation

  • translate 'section-refsig' for German language (PR #2633) (@ahus1)

  • synchronize French README with English version (PR #2637) (@flashcode)

Build / Infrastructure

  • create an official logo for the project (#48) (@mmajko)

  • update Ruby versions in appveyor build matrix (PR #2388) (@miltador)

  • add mailinglist, changelog, source, and issues URI to gem spec

  • allow blocks and substitutions tests to be run directly

  • asciidoctor formula now available for Homebrew (@zmwangx)

Distribution Packages

Eine vollständige Liste der Änderungen in älteren Versionen finden Sie im CHANGELOG.