Was ist AsciiDoc?

The ultimate guide to getting started with AsciiDoc by Chris Chinchilla

AsciiDoc ist eine leichte, für Menschen lesbare, Auszeichnungssprache. Sie wurde 2002 von dem Softwareentwickler Stuart Rackham entwickelt, um das Schreiben von technischen Dokumenten, Büchern, Blogs und sogar Folien zu vereinfachen. AsciiDoc konzentriert sich auf die Struktur und den Inhalt und nicht auf die Formatierung. Dadurch ermöglicht sie den Autoren, gut strukturierte Dokumente zu erstellen, ohne dass komplexe Formatierungswerkzeuge erforderlich sind.

Sie schreiben ein AsciiDoc-Dokument genauso, wie Sie ein normales Textdokument schreiben würden. Es gibt keine Markup-Tags oder seltsame Formatbezeichnungen. AsciiDoc-Dateien sind so konzipiert, dass sie direkt betrachtet, bearbeitet und gedruckt oder in andere Präsentationsformate übersetzt werden können.
Stuart Rackham, Entwickler von AsciiDoc

Hier ist ein Beispiel für die Formatierung in AsciiDoc:

Beispiel für AsciiDoc-Markup-Syntax und gerenderte Ausgabe

Wann sollten Sie AsciiDoc verwenden?

Häufige Anwendungsfälle für AsciiDoc wie Dokumentation, Bücher und Blogs

AsciiDoc wird häufig für technische Dokumentationen verwendet und ist daher ideal für die Erstellung von Softwareanleitungen, API-Handbüchern und Codedokumentation. Sein strukturiertes Format hilft, komplexe Informationen klar zu organisieren. Entwickler und technische Redakteure bevorzugen AsciiDoc wegen seiner Fähigkeit, detaillierte Inhalte effizient zu verwalten. Unternehmen wie Red Hat, die Eclipse Foundation und viele Open-Source-Projekte setzen auf AsciiDoc für ihre offizielle Dokumentation.

Eine weitere häufige Anwendung von AsciiDoc ist das Schreiben von Büchern und E-Books, insbesondere zu technischen oder akademischen Themen. Probieren Sie unsere Buchvorlage oder die Vorlage für wissenschaftliche Arbeiten aus. Verlage wie O'Reilly Media akzeptieren AsciiDoc als Autorenformat. Die Autoren finden, dass die einfache Syntax es ihnen erlaubt, sich auf die Erstellung von Inhalten zu konzentrieren und professionelle Qualität zu produzieren, ohne sich mit der Formatierung zu verzetteln.

AsciiDoc ist auch eine beliebte Wahl für Blogs und Websites. Über den Website Export in adoc Studio, oder Statische Website-Generatoren wie Antora und Jekyll erstellen Sie aus AsciiDoc Dokumenten navigierbare Webseiten. Diese Anwendungen ermöglichen es Content-Teams, Dokumentationsportale direkt aus AsciiDoc-Dateien zu erstellen. Darüber hinaus eignet sich AsciiDoc auch für Folien und Präsentationen — Tools wie Asciidoctor Reveal.js ermöglichen es Ihnen, Präsentationsfolien aus reinem Text zu erstellen. Wie Sie sehen, sind die Anwendungsfälle breit und vielfältig.

Vorteile von AsciiDoc

Wichtige Vorteile von AsciiDoc gegenüber anderen Auszeichnungssprachen
  • Standardisiert: AsciiDoc ist auf dem Weg zur Standardisierung, wobei die AsciiDoc Working Group der Eclipse Foundation die Bemühungen anführt. Andere Auszeichnungssprachen wie Markdown verfügen nicht über einen solchen universellen Standard.
  • Leicht zu lesen, flexible Syntax: AsciiDoc verwendet minimale Tags für Markup, wodurch der Inhalt leicht von den Formatierungsanweisungen im Editor zu unterscheiden ist. Außerdem bietet es mehr Formatierungsoptionen. Während Markdown beispielsweise dieselbe Syntax für Links und Bilder verwendet, bietet AsciiDoc je nach gewünschter Ausgabe unterschiedliche Methoden.
  • Viele Funktionen von Haus aus: AsciiDoc ist eine voll funktionsfähige Auszeichnungssprache ohne Dialekte. Im Gegensatz dazu erfordert Markdown Erweiterungen für Funktionen wie Tabellen, Fußnoten oder Zitate, die nur in Dialekten wie MultiMarkdown vorhanden sind. Das Problem: Die Erweiterung der Markdown-Syntax kann zu Kompatibilitätsproblemen führen, wenn andere Benutzer nicht die gleichen Add-ons installiert haben.
  • Verschiedene Ausgabeformate: Wenn Sie Ihre Inhalte in verschiedenen Formaten (HTML, PDF, etc.) veröffentlichen müssen, bietet AsciiDoc eine nahtlose Möglichkeit, dies mit minimaler Umformatierung zu tun. Einige Anwendungen erlauben Ihnen sogar, ein einziges Stylesheet für alle Formate zu verwenden.
  • Versionierung und Automatisierung: AsciiDoc lässt sich nahtlos in Docs-as-Code-Workflows integrieren und ist damit ideal für Teams, die Versionskontrollsysteme wie Git und CI/CD-Pipelines verwenden. Seine Kompatibilität mit Git und anderen Werkzeugen macht es perfekt für Projekte, bei denen mehrere Personen an der gleichen Dokumentation arbeiten.

Die Philosophie hinter AsciiDoc

AsciiDoc verkörpert eine Philosophie, die auf Einfachheit, Lesbarkeit und Effizienz bei der Erstellung von Inhalten setzt.

Kernphilosophie von AsciiDoc einschliesslich Docs-as-Code und Lesbarkeit
  • Docs-as-Code: AsciiDoc entspricht dem Docs-as-Code-Ansatz, bei dem die Dokumentation wie ein Software-Code behandelt wird. Daher können AsciiDoc-Dateien nahtlos in Versionskontrollsysteme wie Git integriert werden.
  • Leicht lesbar und wartungsfreundlich: Die Syntax von AsciiDoc ist leicht zu lesen und zu pflegen und eignet sich daher ideal für langfristige Projekte und die einfache Einarbeitung neuer Mitarbeiter.
  • Flexibel und erweiterbar: AsciiDoc ist flexibel und erweiterbar, erlaubt benutzerdefinierte Makros und die Integration mit verschiedenen Werkzeugen, was es an verschiedene Dokumentationsanforderungen anpassbar macht.
  • Große, vernetzte Gemeinschaft: AsciiDoc lebt von den Beiträgen der Community und gewährleistet eine kontinuierliche Entwicklung und Relevanz durch gemeinschaftliche Bemühungen.

Ihr erstes AsciiDoc-Dokument

Bevor wir in die Syntax-Details eintauchen, erstellen wir ein vollständiges AsciiDoc-Dokument von Grund auf. So bekommen Sie ein Gefühl dafür, wie AsciiDoc in der Praxis funktioniert. Erstellen Sie eine neue Datei namens mein-erstes-dokument.adoc und fügen Sie folgenden Inhalt ein:

:toc:
:icons: font

= Mein erstes AsciiDoc-Dokument
Max Mustermann <max@example.com>
v1.0, 2026-01-15

== Einleitung

AsciiDoc unterstützt _kursiven_, *fetten* und `monospace` Text.

== Hauptmerkmale

Die Auszeichnungssprache macht das Schreiben strukturierter Dokumente einfach:

* Einfache Syntax für alltägliche Formatierung
* Eingebaute Unterstützung für Tabellen und Listen
* Mehrere Ausgabeformate aus einer einzigen Quelle

// Diese Zeile ist ein Kommentar. Sie ist in der Ausgabe unsichtbar.

=== Eine einfache Tabelle

|===
| Funktion | Unterstützt

| Fetter Text
| Ja

| Tabellen
| Ja

| Fußnoten
| Ja
|===

== Fazit

Das war's! Sie haben Ihr erstes AsciiDoc-Dokument geschrieben.
Weitere Tipps finden Sie in unserem https://www.adoc-studio.app/blog[Blog].

Dieses kurze Dokument demonstriert bereits mehrere Kernkonzepte: einen Dokumentkopf mit Titel, Autor und Version, Attribute wie :toc: für ein automatisches Inhaltsverzeichnis, Textformatierung, eine Liste, eine Tabelle, und einen Link. Öffnen Sie es in adoc Studio oder verarbeiten Sie es mit Asciidoctor und Sie sehen ein vollständig formatiertes Dokument mit einem klickbaren Inhaltsverzeichnis.

Beachten Sie, wie die Quelldatei auch ohne Rendering gut lesbar ist. Das ist eines der zentralen Designprinzipien von AsciiDoc: Der reine Text ist schon für sich allein aussagekräftig, während die gerenderte Ausgabe visuellen Feinschliff hinzufügt. Sie brauchen keine spezielle Software, um AsciiDoc zu lesen oder zu schreiben — jeder Texteditor funktioniert. Aber ein spezialisiertes Tool wie adoc Studio bietet Ihnen die beste Erfahrung mit Live-Vorschau und Syntaxunterstützung.

Erste Schritte mit AsciiDoc

AsciiDoc ist besonders stark, wenn es darum geht, Inhalte auf strukturierte Weise zu organisieren. Sie können große, komplexe Dokumente erstellen, indem Sie sie in kleinere Abschnitte oder Kapitel unterteilen, die separat eingefügt und verwaltet werden können. Schauen wir uns einige der Schlüsselelemente von AsciiDoc an:

Dokumententitel und Metadaten

Jedes AsciiDoc-Dokument beginnt typischerweise mit einem Titel und optionalen Metadaten, die helfen, die Struktur und das Aussehen des Dokuments zu definieren.

  • Dokumententitel: Der Titel wird ganz oben durch ein einzelnes Gleichheitszeichen (=) definiert.
  • Metadaten: Metadaten wie Autor, Revisionsnummer und Datum können unterhalb des Titels hinzugefügt werden.

Grundlagen zu Syntax & Struktur

Überblick über grundlegende AsciiDoc-Syntaxelemente

Titel

Titel bzw. Überschriften werden in AsciiDoc mit dem Gleichheitszeichen (=) erstellt. Die Anzahl der Gleichheitszeichen entspricht der Ebene der Überschrift:

= Dokumenttitel (Ebene 0)
== Abschnittstitel (Ebene 1)
=== Unterabschnitt (Ebene 2)
==== Unter-Unterabschnitt (Ebene 3)

Das ergibt eine klare Dokumenthierarchie, ähnlich wie <h1> bis <h4> in HTML. Beachten Sie, dass der Dokumenttitel (=) nur einmal ganz oben in Ihrer Datei stehen sollte.

Bonus: Hier sind 10 Tipps, um Ihre Überschriften zu verbessern.

Absätze und Textformatierung

Absätze sind einfach Textzeilen, die durch eine Leerzeile getrennt sind. Es ist keine spezielle Syntax erforderlich, um einen Absatz zu definieren. AsciiDoc bietet umfangreiche Formatierungsmöglichkeiten:

Das ist *fetter* Text.
Das ist _kursiver_ Text.
Das ist `Monospace` Text.
Das ist *_fetter und kursiver_* Text.
Das ist #hervorgehobener# Text.
Das ist ^Hoch^stellung und ~Tief~stellung.

Sie können auch die üblichen Tastenkombinationen in adoc Studio verwenden — zum Beispiel ⌘+B für fetten Text.

Listen

AsciiDoc unterstützt mehrere Arten von Listen. Hier sind praktische Beispiele für jeden Typ:

Ungeordnete Liste — verwenden Sie Sternchen (*) für Verschachtelung:

* Element 1
* Element 2
** Verschachteltes Element 2a
** Verschachteltes Element 2b
* Element 3

Geordnete Liste — verwenden Sie Punkte (.) für automatische Nummerierung:

. Erster Schritt
. Zweiter Schritt
.. Unterschritt a
.. Unterschritt b
. Dritter Schritt

Definitionsliste — verwenden Sie doppelte Doppelpunkte (::) um einen Begriff mit seiner Definition zu verbinden:

AsciiDoc:: Eine leichtgewichtige Auszeichnungssprache.
Markdown:: Eine weitere beliebte Auszeichnungssprache.

Checkliste — verwenden Sie [*] für erledigte und [ ] für offene Punkte:

* [*] Einleitung schreiben
* [*] Code-Beispiele einfügen
* [ ] Überprüfen und veröffentlichen

Verknüpfungen

Links in AsciiDoc können mit einer einfachen Syntax erstellt werden:

https://example.com[Beispiel besuchen]
link:dokument.pdf[PDF herunterladen]
<<abschnittstitel,Zum Abschnitt springen>>
mailto:info@example.com[E-Mail senden]
  • Hyperlinks: Externe URLs werden automatisch erkannt, oder verwenden Sie das link:-Makro für lokale Dateien.
  • Interne Verweise: Verwenden Sie <<Anker-ID,Linktext>>, um innerhalb Ihres Dokuments zu verlinken.

Bilder

Fügen Sie Bilder in AsciiDoc einfach mit image:: ein. Sollten Sie das Bild anpassen, wird es automatisch im Dokument aktualisiert, sofern der gleiche Name bestehen bleibt.

image::screenshot.png[Screenshot der App, 600]

Der erste Wert in Klammern ist der Alternativtext, gefolgt von der optionalen Breite. Weitere Details finden Sie in unseren Best Practices für Bilder in AsciiDoc. Sie können auch die Inline-Variante image:icon.png[] (einfacher Doppelpunkt) verwenden, um ein Bild innerhalb einer Textzeile zu platzieren.

Grundlegende AsciiDoc-Syntaxbeispiele für Überschriften, Listen und Links

Erweiterte Syntax und Funktionen

Tabellen

AsciiDoc unterstützt die Erstellung von Tabellen, sowohl einfache als auch komplexe:

|===
| Name | Rolle | Sprache

| Alice
| Entwicklerin
| Java

| Bob
| Designer
| CSS
|===

Für mehr Kontrolle können Sie Spaltenbreiten und Ausrichtung angeben. Verwenden Sie cols=”1,2,3” für proportionale Breiten und <, > oder ^ für links-, rechts- oder zentrierte Ausrichtung.

Makros und Includes

AsciiDoc ermöglicht die Einbindung externer Dateien. Sie behalten die Originaldatei an ihrem Platz und verweisen nur auf sie. Keine Kopien nötig, alle Aktualisierungen sind in Ihrem Dokument sichtbar:

= Mein Handbuch
include::kapitel/einführung.adoc[]
include::kapitel/erste-schritte.adoc[]
include::gemeinsam/glossar.adoc[]

Sie können auch nur bestimmte Zeilen oder markierte Bereiche aus einer Datei einbinden, was nützlich ist, um Code-Ausschnitte aus echten Quelldateien einzubetten. Lesen Sie unseren Leitfaden zur Include-Direktive im Detail für fortgeschrittene Techniken. Erkunden Sie auch Includes in unserem Lernpfad.

include::src/main.py[lines=5..15]
include::src/app.js[tag=setup]

Attribute

Sie können Attribute definieren und in Ihrem Dokument wiederverwenden, was für die Verwaltung von sich wiederholenden Inhalten nützlich ist:

:product-name: adoc Studio
:version: 4.0
:homepage: https://www.adoc-studio.app

Laden Sie {product-name} {version} von {homepage} herunter.

Neben der Verwendung als Variablen können Sie mit Attributen Ihr Dokument weiter anpassen. Zum Beispiel durch Hinzufügen von Seitenzahlen in der PDF-Ausgabe (:pagenums:), Einfügen eines Inhaltsverzeichnisses (:toc:) oder Aktivierung von Syntax-Highlighting (:source-highlighter: highlight.js).

Leitfaden zur Auswahl des richtigen AsciiDoc-Syntaxelements

Hinweise (Admonitions)

Hinweise sind visuelle Hervorhebungsblöcke, die wichtige Informationen kennzeichnen. AsciiDoc unterstützt fünf Typen:

NOTE: Dies ist ein allgemeiner Hinweis für den Leser.

TIP: Ein hilfreicher Tipp zur Verbesserung Ihres Workflows.

WARNING: Seien Sie vorsichtig bei diesem Schritt.

IMPORTANT: Überspringen Sie diese Konfiguration nicht.

CAUTION: Diese Aktion kann nicht rückgängig gemacht werden.

Jeder Typ wird mit einem eigenen Symbol und einer eigenen Farbe dargestellt, sodass Leser kritische Informationen sofort erkennen können. Für technische Dokumentationen lesen Sie unseren Leitfaden zu Warnhinweisen und Sicherheitshinweisen, oder probieren Sie unsere ISO-konformen Hinweis-Styles.

Quellcode-Blöcke

AsciiDoc bietet leistungsstarkes Syntax-Highlighting für Code-Blöcke. Geben Sie die Sprache nach dem öffnenden Begrenzer an:

[source,python]
----

def greet(name):
    return f"Hallo, {name}!"

print(greet("Welt"))
----

Sie können auch Callouts verwenden, um bestimmte Zeilen in Ihrem Code zu erklären:

[source,java]
----

public class Main {
    public static void main(String[] args) { // <1>
        System.out.println("Hallo!"); // <2>
    }
}
----

<1> Einstiegspunkt der Anwendung
<2> Gibt eine Begrüßung auf der Konsole aus

Callouts (die nummerierten Markierungen <1>, <2>) sind eine einzigartige AsciiDoc-Funktion, mit der Sie Code Zeile für Zeile kommentieren können — etwas, das Markdown schlicht nicht kann.

Fußnoten

Fußnoten ermöglichen es Ihnen, ergänzende Informationen hinzuzufügen, ohne den Lesefluss zu unterbrechen:

AsciiDoc wurde 2002 entwickelt.footnote:[Von Stuart Rackham, einem Softwareentwickler aus Neuseeland.]

Der Fußnotentext erscheint am Ende der Seite, automatisch nummeriert. Das ist besonders nützlich für wissenschaftliches Schreiben und technische Referenzen.

Querverweise und Anker

AsciiDoc ermöglicht es Ihnen, Anker zu erstellen und sie von überall im Dokument zu referenzieren:

[[mein-abschnitt]]
== Mein Abschnitt

Siehe <<mein-abschnitt>> für weitere Details.

Abschnittsüberschriften erzeugen automatisch Anker basierend auf ihrem Text, sodass Sie sie direkt mit <<abschnittstitel>> referenzieren können. Für längere Dokumente ist diese Funktion unverzichtbar für die Navigation.

Aber das ist nur die Spitze des Eisbergs. AsciiDoc bietet noch weitere Funktionen wie Bedingungen, um Inhalte basierend auf Attributen ein- oder auszuschließen. Erkunden Sie unseren Lernpfad für eine schnelle Einführung in diese Schlüsselelemente.

Und als Dankeschön dafür, dass Sie bis hierher gelesen haben, finden Sie hier unser AsciiDoc Cheat Sheet mit 33 der wichtigsten AsciiDoc-Syntaxelemente. Weitere Vorlagen finden Sie in unserer Download Sektion.

AsciiDoc Cheat Sheet mit 33 wichtigen Syntaxelementen

Best Practices für das Schreiben in AsciiDoc

Im Laufe der Jahre hat die AsciiDoc-Community mehrere Konventionen etabliert, die Ihre Dokumente leichter zu schreiben, zu prüfen und zu pflegen machen:

Ein Satz pro Zeile. Setzen Sie jeden Satz in eine eigene Zeile. AsciiDoc behandelt aufeinanderfolgende Zeilen als einen einzelnen Absatz, sodass die Ausgabe gleich aussieht. Der Vorteil: Versionskontrollsysteme wie Git können Änderungen auf Satzebene verfolgen, was Diffs deutlich lesbarer macht. Erfahren Sie mehr darüber, wie Git das technische Schreiben verändert hat.

Dies ist der erste Satz.
Dies ist der zweite Satz.
Sie werden als ein Absatz gerendert.

Verwenden Sie Includes für große Dokumente. Teilen Sie Ihren Inhalt in separate Dateien auf und kombinieren Sie sie mit include:: — siehe unseren Leitfaden zur Include-Direktive. So bleibt jede Datei übersichtlich und mehrere Autoren können gleichzeitig an verschiedenen Abschnitten arbeiten:

= Benutzerhandbuch
include::kapitel/einführung.adoc[]
include::kapitel/installation.adoc[]
include::kapitel/konfiguration.adoc[]

Verwenden Sie Attribute für wiederkehrende Werte. Definieren Sie Produktnamen, Versionsnummern oder URLs als Attribute. Wenn sie sich ändern, aktualisieren Sie sie an einer Stelle:

:product-name: adoc Studio
:version: 4.0

Laden Sie {product-name} {version} noch heute herunter.

Organisieren Sie Bilder in einem eigenen Ordner. Setzen Sie das :imagesdir:-Attribut, um Ihre Bildpfade sauber zu halten:

:imagesdir: images

image::screenshot.png[Mein Screenshot]

Verwenden Sie Bedingungen für Multi-Target-Publishing. Wenn Ihr Dokument verschiedene Zielgruppen oder Formate bedient, verwenden Sie ifdef, ifndef oder ifeval, um zu steuern, was einbezogen wird:

ifdef::backend-pdf[]
Dieser Text erscheint nur in der PDF-Ausgabe.
endif::[]

Verwendung von AsciiDoc mit CSS-Stylesheets

Eine der Stärken von AsciiDoc ist seine Fähigkeit, mit CSS gestaltet zu werden, insbesondere bei der Erzeugung von HTML-Ausgaben. Dies ermöglicht einen hohen Grad an Anpassung des Erscheinungsbildes Ihrer Dokumente.

  • Benutzerdefinierte Stile: Sie können bei der Konvertierung von AsciiDoc nach HTML eine Verknüpfung zu einer benutzerdefinierten CSS-Datei herstellen, die es Ihnen ermöglicht, Ihre eigenen Stile anzuwenden.
  • Themendateien: Asciidoctor unterstützt Themendateien, die das Styling von PDFs und anderen Formaten steuern können. Probieren Sie unsere ISO-konformen Stylesheets oder den Tufte-Stil als Inspiration.

Es ist wichtig, zwischen den AsciiDoc-Konvertern zu unterscheiden. Zum Beispiel verwendet Asciidoctor unterschiedliche “Sprachen” für PDF- und HTML-Ausgaben. Während HTML auf CSS basiert, benötigt AsciidoctorPDF ein separates Tool für die PDF-Konvertierung. Im Gegensatz dazu verwenden Tools wie adoc&nbsp;Studio CSS sowohl für HTML als auch für PDF, so dass Sie ein einziges Stylesheet für alle Exporte verwenden können.

Wir verwenden AsciiDoc, um sicherzustellen, dass unsere Projektdokumente in verschiedenen Formaten, von Kundenpräsentationen bis zu internen Berichten, einheitlich gestaltet sind. Es ermöglicht uns, die Einheitlichkeit zu wahren und gleichzeitig flexibel zu sein, wie wir bestimmte Informationen anzeigen, insbesondere im Hinblick auf die Zugänglichkeit in verschiedenen Formaten wie HTML, PDF oder ePub.
Daniel Roberts, LavaRoofing CEO

AsciiDoc vs. Word, Google Docs & Co.

Jetzt werden Sie sich vielleicht fragen: Warum sollten wir all diese ausgefallenen Tags lernen, wenn wir einfach auf eine Schaltfläche klicken oder ein Tastenkürzel drücken können? Oder anders formuliert: Warum bleiben wir nicht bei MS Word oder Google Docs?

Vergleich von Auszeichnungssprachen und WYSIWYG-Editoren

MS Word und Google Docs sind What You See Is What You Get (WYSIWYG)-Editoren. WYSIWYG-Editoren ermöglichen es den Nutzern, die endgültige Ausgabe zu sehen, während sie schreiben und Stile, Formatierungen und visuelle Elemente direkt anwenden. Sie eignen sich hervorragend für kürzere Texte, aber sobald die Dokumente größer werden, gibt es einige Einschränkungen.

WYSIWYG-Editoren schränken die Wiederverwendung von Inhalten über verschiedene Plattformen und Formate hinweg ein. Ihre enge Integration von Inhalt und Darstellung macht die Anpassung an Ausgaben wie HTML oder PDF ohne manuelle Anpassungen schwierig. Im Gegensatz dazu ermöglichen Auszeichnungssprachen das Single-Source-Publishing, bei dem ein Masterdokument mehrere Ausgaben mit unterschiedlichen Formaten und Stilen erzeugt - etwas, das WYSIWYG-Editoren nicht effizient handhaben können.

Außerdem haben WYSIWYG-Editoren Probleme mit der Versionierung. Der „Docs-as-Code“-Ansatz, bei dem Dokumente wie Code behandelt werden, stützt sich auf Tools wie Git. Auszeichnungssprachen wie AsciiDoc erzeugen reine Textdateien, die sich ideal für die Versionskontrolle eignen, während WYSIWYG-generierte Dateien, die als Binärdateien behandelt werden, diese Funktionalität einschränken.

Schließlich ermöglichen Auszeichnungssprachen die dynamische Integration externer Dateien, wodurch die Dokumente stets auf dem neuesten Stand sind. WYSIWYG-Editoren hingegen erfordern oft manuelle Aktualisierungen, was die Verwaltung der Inhalte mühsamer macht.

AsciiDoc vs. Markdown

AsciiDoc gehört zu einer Klasse von Auszeichnungssprachen, die „leichtgewichtig“ sind, weil sie einen minimalistischen und leicht lesbaren Ansatz zur Textformatierung bieten wollen. Beispiele für ähnliche Sprachen sind Markdown und reStructuredText. Was AsciiDoc auszeichnet, ist die Fähigkeit, komplexe Inhaltsstrukturen zu handhaben und dabei einfach zu erlernen und zu benutzen zu sein. Ein konkretes Beispiel: Im direkten Vergleich mit Markdown und LaTeX benötigt AsciiDoc die wenigstens Zeichen, um einfache Syntaxelemente im Text einzufügen.

Während Markdown eine bekanntere Auszeichnungssprache ist, bietet AsciiDoc mehrere Vorteile, wenn es um komplexere Schreibaufgaben geht:

Um die Unterschiede greifbarer zu machen, hier ein direkter Vergleich der wichtigsten Funktionen:

Funktion AsciiDoc Markdown
Tabellen Nativ, mit Spaltenverbindung und Ausrichtung Nur einfach (via GFM-Erweiterung)
Fußnoten Native Unterstützung Erweiterung erforderlich
Inhaltsverzeichnis Automatisch generiert via :toc:-Attribut Nicht unterstützt
Hinweise (NOTE, TIP, WARNING) Nativ eingebaut Nicht unterstützt
Datei-Includes include::datei.adoc[] Nicht unterstützt
Querverweise <<anker-id>> mit automatischer Nummerierung Nicht unterstützt
Bedingte Inhalte ifdef / ifndef-Direktiven Nicht unterstützt
Dokumentattribute (Variablen) :name: wert mit {name} Nicht unterstützt
Eigene Stile CSS für HTML und PDF Eingeschränkt
Syntax-Highlighting Nativ mit source-Blöcken Erweiterung erforderlich
Standardisierung In Arbeit durch die Eclipse Foundation Working Group Kein universeller Standard (viele Dialekte)
Ausgabeformate HTML, PDF, EPUB, DocBook, man pages Hauptsächlich HTML

Wie Sie sehen, deckt AsciiDoc viele Funktionen nativ ab, die Markdown entweder gar nicht oder nur über Erweiterungen von Drittanbietern unterstützt. Das ist besonders relevant für Teams, die eine zuverlässige und konsistente Syntax über Projekte hinweg benötigen.

Das Problem mit Markdown […] - „Dialekte“, Nicht-Standardisierung usw. - machen seine scheinbare Einfachheit zu einer Illusion. Sobald Asciidoc einen endgültigen Standard hat, wird es noch überzeugender sein.
Peter Kenny, AsciiDoc Nutzer

Migration von Markdown zu AsciiDoc

Viele Autoren beginnen mit Markdown und stellen später fest, dass sie die fortgeschritteneren Funktionen von AsciiDoc benötigen. Für einen umfassenden Schritt-für-Schritt-Ansatz lesen Sie unser vollständiges Migrations-Handbuch. Erfahren Sie auch, wie Ping Identity zu AsciiDoc migriert hat. Die gute Nachricht: Die Migration ist unkompliziert und es gibt Anwendungen, die es Ihnen erleichtern.

Automatische Konvertierungstools. Sie müssen Dateien nicht manuell konvertieren. Mehrere Tools können helfen:

  • Kramdoc (auch bekannt als markdown2asciidoc): Konvertiert Markdown-Dateien ins AsciiDoc-Format unter Beibehaltung von Struktur und Formatierung.
  • Pandoc: Ein universeller Dokumentkonverter, der unter Dutzenden anderen Formaten auch Markdown-zu-AsciiDoc-Konvertierung unterstützt. Führen Sie pandoc -f markdown -t asciidoc input.md -o output.adoc aus.

Häufige Stolperfallen bei der Migration:

  • Markdowns **fett** wird zu *fett* in AsciiDoc (einfache Sternchen). Doppelte Sternchen haben in AsciiDoc eine andere Bedeutung (unbeschränkter Fettdruck).
  • Links sind umgekehrt: Markdown verwendet [text](url), während AsciiDoc url[text] verwendet.
  • Die Bildsyntax unterscheidet sich: Markdowns ![alt](pfad) wird zu image::pfad[alt] in AsciiDoc. Beachten Sie den doppelten Doppelpunkt für Blockbilder.

Tools und Plugins für AsciiDoc

Wenn es um die Arbeit mit AsciiDoc geht, kann die Wahl des richtigen Werkzeugs einen bedeutenden Unterschied in Ihrer Produktivität und der Qualität Ihrer Arbeit ausmachen. Es gibt zwei Hauptkategorien von Werkzeugen: Integrierte Entwicklungsumgebungen (IDEs; aus dem Englischen: Integrated Development Environment) und spezielle AsciiDoc-Editoren wie adoc Studio.

adoc Studio

adoc Studio App-Symbol

Mit adoc Studio können Sie jederzeit und überall an Ihren Texten arbeiten. Schreiben, bearbeiten, korrigieren und veröffentlichen Sie Ihre Arbeit als PDF und HTML, ohne ein Terminal benutzen zu müssen.

Es bietet eine benutzerfreundliche Umgebung, die die Arbeit mit AsciiDoc für jeden zugänglich macht, vom Anfänger bis zum fortgeschrittenen Benutzer. Die Software ist für Mac, iPad und iPhone erhältlich. Alle Funktionen entdecken.

Vorteile von adoc Studio

  • AsciiDoc ohne Terminal: In adoc Studio schreiben Sie Ihren Text im Editor und sehen ihn sofort in der Vorschau auf der rechten Seite. Unser eigener Parser sorgt dafür, dass die Vorschau immer das aktuelle HTML- oder PDF-Dokument wiedergibt. Andere Konverter wie Asciidoctor erfordern Befehlszeilenbefehle und komplexe Skripte.
  • Gleiches CSS-Stylesheet für HTML und PDF: Verwenden Sie fertige Vorlagen oder Ihre eigenen CSS-Stile für das Design - egal ob HTML oder PDF - mit einem einzigen Stylesheet für alle Ausgaben. Andere Konverter, wie Asciidoctor, benötigen unterschiedliche Vorlagensprachen für verschiedene Formate, wie Asciidoctor für HTML und AsciidoctorPDF für PDF.
  • Intuitive Benutzeroberfläche: adoc Studio wurde mit Blick auf die Benutzerfreundlichkeit entwickelt und verfügt über eine übersichtliche, intuitive Benutzeroberfläche, die die Lernkurve im Vergleich zu herkömmlichen AsciiDoc-Tools vereinfacht. Um die Benutzerfreundlichkeit weiter zu erhöhen, haben wir adoc Coach entwickelt, ein Menü zur Syntaxvervollständigung, das die Syntax-Elemente direkt im Text vorschlägt und erklärt.

Asciidoctor

Asciidoctor-Logo

Asciidoctor ist eine Implementierung der AsciiDoc-Sprache. Es ist eine schnelle Open-Source-Toolchain, die AsciiDoc-Dateien verarbeitet und sie in Formate wie HTML, PDF und ePub konvertiert.

Obwohl es leistungsstarke Funktionen wie IDE-Integration und Plugin-Unterstützung bietet, verfügt Asciidoctor nicht über eine native Anwendung und muss über das Terminal ausgeführt werden, was für Nicht-Entwickler entmutigend sein kann. Lesen Sie unseren ausführlichen Vergleich von Asciidoctor und adoc Studio.

Verwendung von IDEs für AsciiDoc

IDEs bieten Entwicklern umfassende Werkzeuge zum Schreiben, Bearbeiten, Testen und Debuggen von Code an einem Ort. Funktionen wie Syntaxhervorhebung, Code-Vervollständigung und Debugging-Tools machen IDEs für die Softwareentwicklung äußerst vielseitig. Viele beliebte IDEs, einschließlich Visual Studio Code und IntelliJ IDEA, unterstützen AsciiDoc durch Plugins und Erweiterungen, die eine nahtlose Integration mit Asciidoctor ermöglichen. Allerdings gibt es auch einige Nachteile bei der Verwendung von IDEs und SSGs anstelle einer nativen Anwendung.

Um Asciidoctor in Visual Studio Code zu verwenden, folgen Sie diesen Schritten:

1. Installieren Sie die AsciiDoc-Erweiterung:

  • Öffnen Sie Visual Studio Code und navigieren Sie zum Erweiterungsmarktplatz.
  • Suchen Sie nach „AsciiDoc“ und installieren Sie die AsciiDoc by Asciidoctor Erweiterung.

2. Vorschau von AsciiDoc-Dateien:

  • Öffnen Sie eine beliebige .adoc-Datei im Editor. Wenn die Erweiterung installiert ist, wird VS Code automatisch eine Live-Vorschau in einem geteilten Fenster anzeigen.
  • Sie können die Vorschau mit der Befehlspalette (Strg+Umschalt+P) und der Auswahl von AsciiDoc: Toggle Preview ein- und ausschalten.

3. AsciiDoc nach HTML oder PDF exportieren:

Nachdem Sie Ihren AsciiDoc-Inhalt geschrieben haben, benutzen Sie die Asciidoctor CLI, um die Datei in Ihr gewünschtes Format zu konvertieren. Um z.B. nach HTML zu konvertieren, öffnen Sie ein Terminal in VS Code und führen Sie aus:

asciidoctor mydocument.adoc

Um in PDF zu konvertieren, benötigen Sie einen zweiten Befehl:

asciidoctor-pdf mydocument.adoc

Eine vollständige Anleitung finden Sie in unserem Export-Guide für jedes Betriebssystem.

Je komplexer Ihr Projekt wird, desto länger und komplizierter werden die Skripte, die für den Export von Dokumenten in mehrere Formate wie HTML und PDF erforderlich sind. Die Verwaltung unterschiedlicher Stile, Layouts und Medieninhalte in verschiedenen Formaten erhöht den Bedarf an aufwendigeren Skripten.

Als wir beispielsweise an unserer Merlin Project Dokumentation arbeiteten, mussten wir ein komplexeres Skript erstellen und ausführen, um die korrekte Formatierung sowohl in der HTML- als auch in der PDF-Ausgabe sicherzustellen. Dieses Skript behandelte bedingten Text, benutzerdefinierte Stylesheets und eingebettete Ressourcen, um die Konsistenz und Qualität in allen Formaten zu gewährleisten.

Terminal mit komplexen Asciidoctor-Exportskripten für Mehrformat-Ausgabe

Ressourcen und weiterführende Literatur

Dies sollte für einen umfassenden Überblick über AsciiDoc ausreichen. Wenn Sie jedoch Lust auf mehr haben, finden Sie hier eine Liste von Ressourcen mit weiteren Informationen.

Video-Tutorials: Erkunden Sie unseren AsciiDoc-Lernpfad in adoc Studio. In leicht verständlichen Kapiteln lernen Sie die Dokumentenerstellung in AsciiDoc kennen. Sie können uns auch auf YouTube folgen, um weitere Tutorial-Videos zu sehen.

Syntax-Referenzen, Q&A-Seiten und Community-Foren:

Wenn Sie wissen wollen, warum wir uns entschieden haben, unsere eigene AsciiDoc-Schreibumgebung zu entwickeln, schauen Sie sich unser Making Of an.

Abschließende Worte

AsciiDocs Flexibilität und Leistungsfähigkeit machen es für Autoren von Inhalten unverzichtbar, besonders in technischen Bereichen. Seine Fähigkeit, qualitativ hochwertige Multiformat-Dokumente aus einer einzigen Quelle zu generieren, gewährleistet konsistente, ausgefeilte Inhalte auf verschiedenen Plattformen mit minimalem Aufwand. Dafür sorgen beispielsweise Templates und Stylesheets.

Egal, ob Sie ein Einzelentwickler, technischer Autor oder Teil eines großen Teams sind, AsciiDoc bietet Ihnen die Werkzeuge, um erfolgreich zu sein. Wenn Sie die Strategien in diesem Handbuch anwenden, können Sie Ihre Inhalte effizient erstellen, verwalten und veröffentlichen.

Wenn Sie AsciiDoc in Ihren Arbeitsablauf integrieren, werden Sie feststellen, dass seine Einfachheit, gepaart mit seinen robusten Fähigkeiten, eine komplette Lösung für moderne Dokumentationsanforderungen bietet.

FAQs (Häufig gestellte Fragen)

Was ist AsciiDoc?
AsciiDoc ist eine leichtgewichtige, menschenlesbare Markup-Sprache, die zum Schreiben technischer Dokumente, Bücher, Blogs und mehr entwickelt wurde. Sie ermöglicht es Ihnen, in einfachem Text zu schreiben und Ihren Inhalt in verschiedene Formate wie HTML, PDF und DocBook umzuwandeln.

Wer hat AsciiDoc erstellt und wann?
AsciiDoc wurde 2002 von Stuart Rackham erstellt. Er entwickelte es, um eine einfache, aber leistungsfähige Alternative zu herkömmlichen Dokumentformatierungstools anzubieten.

Wie unterscheidet sich AsciiDoc von Markdown und anderen Markup-Sprachen?
Während Markdown vor allem für seine Einfachheit bekannt ist, bietet AsciiDoc eine standardisiertere Syntax, umfangreiche integrierte Funktionen und größere Flexibilität bei der Handhabung komplexer Dokumente. Dies macht es ideal für detaillierte technische Dokumentationen und groß angelegte Projekte.

Welche Vorteile bietet die Verwendung von AsciiDoc gegenüber WYSIWYG-Editoren wie MS Word oder Google Docs?
AsciiDoc trennt Inhalt und Darstellung, was die Versionskontrolle und Zusammenarbeit erleichtert. Es unterstützt Single-Source-Publishing über mehrere Formate hinweg und integriert sich nahtlos in Tools wie Git, was besonders in Docs-as-Code-Workflows von Vorteil ist.

Wie kann ich mit AsciiDoc beginnen?
Sie können damit beginnen, eine einfache Textdatei mit der AsciiDoc-Syntax zu erstellen. Tools wie Asciidoctor, adoc Studio oder Erweiterungen für IDEs wie Visual Studio Code ermöglichen es Ihnen, Ihre Dokumente in verschiedenen Ausgabeformaten anzuzeigen und zu konvertieren.

Welche Ausgabeformate werden von AsciiDoc unterstützt?
AsciiDoc kann in verschiedene Formate konvertiert werden, darunter HTML, PDF, DocBook und ePub. Die verfügbaren Formate können von den verwendeten Tools zur Konvertierung abhängen.

Kann ich meine AsciiDoc-Dokumente mit CSS gestalten?
Ja. Bei der Erstellung von HTML-Ausgaben können Sie benutzerdefinierte CSS-Dateien einbinden, um Ihr Dokument zu gestalten. Einige Tools ermöglichen es sogar, ein einziges Stylesheet für sowohl HTML- als auch PDF-Ausgaben zu verwenden.

Welche Tools und Editoren werden für die Arbeit mit AsciiDoc empfohlen?
Beliebte Optionen umfassen:
  • adoc Studio: Ein dedizierter, nativer AsciiDoc-Editor, der eine intuitive Benutzeroberfläche und eine Live-Vorschau bietet.
  • Asciidoctor: Eine Befehlszeilen-Toolchain zur Verarbeitung von AsciiDoc-Dateien.

  • IDEs wie Visual Studio Code und IntelliJ IDEA unterstützen AsciiDoc ebenfalls über Plugins und Erweiterungen.


Wie integriert sich AsciiDoc in Versionskontrollsysteme?
Da AsciiDoc-Dateien als Klartext vorliegen, funktionieren sie gut mit Versionskontrollsystemen wie Git. Dies ermöglicht eine reibungslose Zusammenarbeit und einen Docs-as-Code-Ansatz.

Was ist der Unterschied zwischen AsciiDoc und Asciidoctor?
AsciiDoc ist die Auszeichnungssprache — die Syntax und Regeln zum Schreiben von Dokumenten. Asciidoctor ist ein Software-Tool (Prozessor), das AsciiDoc-Dateien liest und in Ausgabeformate wie HTML oder PDF konvertiert. Stellen Sie es sich so vor: AsciiDoc ist die Sprache, Asciidoctor ist der Compiler.

Wie erstelle ich ein Inhaltsverzeichnis in AsciiDoc?
Fügen Sie einfach das Attribut :toc: in Ihren Dokumentkopf ein. AsciiDoc generiert automatisch ein klickbares Inhaltsverzeichnis basierend auf Ihren Abschnittsüberschriften. Sie können die Platzierung mit :toc: left, :toc: right oder :toc: preamble steuern.

Kann ich mathematische Formeln in AsciiDoc schreiben?
Ja. AsciiDoc unterstützt STEM-Notation (Science, Technology, Engineering, Mathematics). Fügen Sie :stem: latexmath in Ihren Dokumentkopf ein und verwenden Sie dann stem:[Formel] für Inline-Formeln oder einen eigenen STEM-Block für größere Gleichungen. Dies unterstützt die LaTeX-Math-Syntax. Siehe unser STEM-Formeln Tutorial.

Wie strukturiere ich ein großes Dokument mit mehreren Dateien?
Verwenden Sie die include::-Direktive, um Ihr Dokument in separate Dateien aufzuteilen. Erstellen Sie eine Hauptdatei, die Kapiteldateien einbindet wie include::kapitel-01.adoc[]. Jedes Kapitel kann unabhängig bearbeitet werden. Dies ist besonders nützlich für Bücher, Handbücher und kollaborative Projekte. Erfahren Sie mehr über Sammeldokumente.

Kann ich meine bestehenden Markdown-Dateien zu AsciiDoc migrieren?
Ja. Tools wie Kramdoc und Pandoc können Markdown automatisch in AsciiDoc konvertieren. Führen Sie beispielsweise pandoc -f markdown -t asciidoc input.md -o output.adoc auf der Kommandozeile aus. Überprüfen Sie nach der Konvertierung die Ausgabe, um sicherzustellen, dass alle Formatierungen korrekt übernommen wurden. Lesen Sie unser vollständiges Migrations-Handbuch für weitere Details.