AsciiDoc‑Dateien als PDF exportieren: Leitfaden für jedes OS

Diese Anleitung stellt verschiedene Arbeitsabläufe unter macOS, iOS, Windows und Linux vor, mit denen Sie AsciiDoc‑Dateien in PDF umwandeln können. Wir erklären Ihnen die Installation der benötigten Werkzeuge sowie deren schrittweisen Einsatz auf jeder Plattform. Für Fortgeschrittene beschreiben wir zusätzliche Toolchains, falls Sie besondere Anpassungen benötigen (beispielsweise LaTeX‑Ausgabe). Grundlegende Terminal‑Kenntnisse werden vorausgesetzt; AsciiDoc‑Erfahrung hingegen nicht.

macOS und iOS: Arbeiten mit adoc Studio (AsciiDoc‑App)

adoc Studio ist ein All‑in‑One‑Editor für Mac, iPad und iPhone, der PDFs ohne manuelle Installation weiterer Toolchains exportieren kann. Die App zeigt eine Live‑Vorschau an und nutzt ein einheitliches, CSS‑basiertes Styling sowohl für HTML‑ als auch für PDF‑Ausgaben.

• AsciiDoc‑Datei öffnen: Starten Sie adoc Studio und öffnen Sie Ihre .adoc‑Datei (oder erstellen Sie ein neues Dokument). Die Oberfläche ist zweigeteilt: links der Editor, rechts die Vorschau. Während Sie schreiben, sehen Sie das formatierte Ergebnis in Echtzeit.
• Zur PDF‑Vorschau wechseln: Standardmäßig zeigt die Vorschau HTML an. Klicken Sie oben in der Werkzeugleiste auf das Augensymbol (Vorschau umschalten) und wählen Sie im Dropdown „PDF“. Siehe Screenshot unten. Damit wird Ihr Dokument wie später im PDF dargestellt.

• Als PDF exportieren: Wenn Sie mit der Vorschau zufrieden sind, exportieren Sie die PDF‑Datei.

  • macOS: Datei → Exportieren → PDF oder den Teilen/Exportieren‑Button in der Werkzeugleiste wählen.

  • iPad/iPhone: Export‑/Teilen‑Symbol tippen und „Als PDF exportieren“ auswählen (oder über das iOS‑„Teilen“‑Menü in Dateien sichern bzw. versenden).
    Es entsteht eine PDF‑Datei mit dem aktuellen Styling.
• Exporteinstellungen anpassen: In adoc Studio hängen die Exportoptionen an den Produkt‑Stilen. Öffnen Sie diese über Datei → Exportieren → Produkte… oder mit ⌃ ⌘ E.
  Hier wählen oder erstellen Sie ein Thema (Theme) für Ihre PDF‑Ausgabe, z. B. „Asciidoctor“ oder ein eigenes. Ein Stil besteht im Wesentlichen aus CSS‑Dateien, die Layout und Design für HTML und PDF definieren. Sie können vorhandene Stile duplizieren und anpassen.
• Stile per CSS anpassen: Ein Alleinstellungsmerkmal von adoc Studio ist das CSS‑basierte PDF‑Design dank der integrierten Vivliostyle‑Engine (CSS‑Paged‑Media‑Renderer). Dieselbe CSS‑Datei formatiert HTML und PDF; mit Media Queries richten Sie Regeln gezielt auf PDF:

@media vivliostyle {     
    @page {          size: A4 portrait;          margin: 2cm;     
    }     

    /* Weitere PDF‑spezifische Regeln */ 
}

Der @media vivliostyle Block passt lediglich die PDF Ausgabe an. Über CSS passen Sie Schriftarten, Farben, Ränder oder das Ein‑/Ausblenden bestimmter Elemente an. adoc Studio liefert ein Standard‑Theme („Standard“), das sich nach Belieben ändern lässt – etwa Überschriften‑Schriften ersetzen oder ein Firmenlogo auf dem Titelblatt einblenden.

• AsciiDoc‑Attribute für PDF: Zusätzlich steuern Sie die PDF‑Struktur mit AsciiDoc‑Attributen, ganz ohne Code. Beispiel:

  • :title-page: fügt eine Titelseite ein

  • :front-cover-image: definiert ein Deckblattbild
  • :pagenums: schaltet Seitenzahlen ein/aus
    Auch Fußnoten werden unterstützt – standardmäßig unten auf jeder Seite (über :footnotes-position:änderbar).

macOS: Homebrew + Asciidoctor PDF (Kommandozeile)

Wenn Sie lieber mit der Kommandozeile arbeiten oder automatisieren möchten, setzen Sie auf die Asciidoctor‑PDF‑Toolchain unter macOS. Dazu installieren Sie Ruby und das Gem asciidoctor‑pdf. Homebrew vereinfacht dies, da es Pakete für Ruby und Asciidoctor bereitstellt.

• Homebrew installieren (falls noch nicht vorhanden):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Besuchen Sie brew.sh für Details.

• Asciidoctor installieren (Ruby):

brew install asciidoctor

Homebrew nutzt dabei die System‑Ruby von macOS. Das Paket enthält Asciidoctor für HTML/DocBook, jedoch nichtdas PDF‑Gem.

• Asciidoctor‑PDF‑Gem installieren:

gem install asciidoctor-pdf

Optional für Syntax‑Highlighting:

• PDF erzeugen: Wechseln Sie in das Verzeichnis Ihrer .adoc‑Datei und führen Sie aus:

asciidoctor-pdf myDocument.adoc

Das Ergebnis myDocument.pdf liegt im selben Ordner. Prüfen Sie bei Bedarf den Pfad mit which asciidoctor-pdf.

• PDF anpassen (Themes): Asciidoctor PDF nutzt YAML‑Themen‑Dateien. Um ein eigenes Theme zu erstellen, generieren Sie zunächst die Standard‑Vorlage, passen diese an und verwenden anschließend:

asciidoctor-pdf -a pdf-theme=./my-custom-theme.yml myDocument.adoc

Weitere AsciiDoc‑Attribute wie :doctype: book, :toc:, :pagenums: oder :title-page: funktionieren ebenfalls.

Der Nachteil ist jedoch, dass diese Skripte schnell komplexer werden. Ein Beispiel des Skriptes, welches wir für die Dokumentation von Merlin Project genutzt haben:

Windows Workflows

Unter Windows gibt es mehrere Wege, AsciiDoc in PDF zu wandeln.

Windows: Using WSL (Windows Subsystem für Linux)

WSL ermöglicht eine Linux‑Umgebung unter Windows 10/11 – perfekt für Asciidoctor.

• WSL aktivieren (PowerShell als Administrator):

wsl --install

Dadurch wird standardmäßig Ubuntu installiert. Nach dem Neustart legen Sie im Ubuntu‑Fenster einen UNIX‑Benutzer an.

• Asciidoctor in WSL installieren:

sudo apt update
sudo apt install asciidoctor ruby-asciidoctor-pdf -y

PDF erzeugen: Windows‑Laufwerke finden Sie unter /mnt/c/. Beispiel:

asciidoctor-pdf /mnt/c/Docs/file.adoc

Die Datei file.pdf erscheint anschließend in C:\Docs.

Tip: You can edit the AsciiDoc using your favorite Windows editor (VS Code, Notepad++, etc.) and just use WSL for the conversion command. Or you can edit within WSL using editors like vim or nano if you prefer command-line editing.

Windows: Ruby + Asciidoctor‑PDF nativ (Mise)

Falls WSL nicht infrage kommt, installieren Sie Ruby direkt unter Windows, z. B. mit Mise.

• Mise installieren (via Winget):

winget install jdx.mise

• Shell‑Aktivierung (PowerShell‑Profil):

echo 'mise activate pwsh | Out-String | Invoke-Expression' >> $HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1

Danach PowerShell neu starten.

• Ruby mit Mise installieren:

mise use -g ruby@latest

• Asciidoctor + PDF‑Gem installieren:

gem install asciidoctor asciidoctor-pdf

• PDF konvertieren:

asciidoctor-pdf C:\Docs\myDocument.adoc

Web‑basiert: AsciiDocLive

Wenn Sie nichts installieren können oder möchten, nutzen Sie AsciiDocLive als Online‑Editor.

1. AsciiDocLive öffnen und Ihren AsciiDoc‑Text links einfügen.
2. HTML exportieren und lokal speichern.
3. HTML → PDF: Öffnen Sie die Datei im Browser und drucken Sie „Als PDF sichern“ oder verwenden Sie ein Tool wie wkhtmltopdf.

Linux Workflows

On Linux, AsciiDoc to PDF conversion is typically done via Asciidoctor (Ruby) or the older a2x toolchain. We’ll cover three methods: the native Asciidoctor PDF gem, the DocBook/FOP method, and the newer web-based PDF generator.

Linux: Asciidoctor PDF (Ruby‑Gem)

Die meisten Distributionen bieten Asciidoctor in ihren Repositories.

sudo apt-get install -y asciidoctor ruby-asciidoctor-pdf

Falls die Paketversion veraltet ist, installieren Sie über Gems:

sudo apt-get install -y ruby-full build-essential zlib1g-dev 
gem install asciidoctor asciidoctor-pdf gem install rouge

Konvertieren Sie anschließend mit asciidoctor-pdf file.adoc und passen Sie per Theme oder Attributen an.

all: mydoc.pdf

mydoc.pdf: *.adoc
    asciidoctor-pdf -r asciidoctor-diagram -a toc -a pdf-theme=theme.yml main.adoc -o mydoc.pdf

Linux: asciidoctor‑fopub (DocBook XSL‑FO)

asciidoctor‑fopub nutzt DocBook /XSL‑FO mit Apache FOP für PDFs – ideal, wenn Sie komplexe Layouts oder bestehende DocBook‑Workflows haben.

• Java installieren (sudo apt install default-jdk)
• Repository klonen und bauen:

git clone https://github.com/asciidoctor/asciidoctor-fopub.git cd asciidoctor-fopub ./gradlew clean assemble

• AsciiDoc → DocBook → PDF

asciidoctor -b docbook -o temp.xml myDocument.adoc

Für Anpassungen bearbeiten Sie die DocBook‑XSL‑Stylesheets oder übergeben Sie einen eigenen XSL‑Pfad mit -t.

./fopub temp.xml

Die Workflows im Vergleich

• Diagramme erst nach gem install asciidoctor-diagram