Der ausführliche Leitfaden zu AsciiDoc in 2024

Was ist AsciiDoc?

AsciiDoc ist eine leichte, für Menschen lesbare, Auszeichnungssprache. Sie wurde entwickelt, um das Schreiben von technischen Dokumenten, Büchern, Blogs und sogar Folien zu vereinfachen.

AsciiDoc wurde 2002 von Stuart Rackham entwickelt, einem Softwareentwickler, der den Bedarf an einer leichten, einfachen Textauszeichnungssprache erkannte, die in verschiedene Ausgabeformate wie HTML, PDF und DocBook konvertiert werden kann. 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.

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

Warum sollten Sie AsciiDoc verwenden?

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:

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

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.

Wann sollten Sie AsciiDoc verwenden?

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.

Eine weitere häufige Anwendung von AsciiDoc ist das Schreiben von Büchern und E-Books, insbesondere zu technischen oder akademischen Themen. 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. Auch für Blogs und Websites sowie für Folien und Präsentationen wird AsciiDoc gerne verwendet. Wie Sie sehen können, sind die Anwendungsfälle endlos.

---

Die Philosophie hinter AsciiDoc

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

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

---

AsciiDoc versus 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?

MS Word und Google Docs sind unter anderem 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.

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

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

• = Überschrift der Ebene 1

• == Überschrift der Ebene 2

• === Ebene 3 Überschrift

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

Absätze: Absätze sind einfach Textzeilen, die durch eine Leerzeile getrennt sind. Es ist keine spezielle Syntax erforderlich, um einen Absatz zu definieren. Heben Sie bestimmte Wörter durch Formatierung hervor. Setzen Sie dazu entweder die Tags selbst, oder verwenden Sie die üblichen Tastenkombinationen (⌘+B für fetten Text).

Listen: AsciiDoc unterstützt mehrere Arten von Listen, darunter ungeordnete, geordnete und Beschreibungslisten.

• Ungeordnete Liste: Verwenden Sie ein Sternchen (*) oder einen Bindestrich (-), um ungeordnete Listenelemente zu erstellen.

• Geordnete Liste: Verwenden Sie einen Punkt (.) nach einer Zahl, um geordnete Listenelemente zu erstellen.

• Definitionsliste: Verwenden Sie doppelte Doppelpunkte (::) nach dem zu beschreibenden Begriff.

Verknüpfungen: Links in AsciiDoc können mit einer einfachen Syntax erstellt werden.

• Hyperlinks: http://example.com[Hier Text einfügen]

• Interne Verweise: <<Anker-ID,Hier Text einfügen>>

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

Erweiterte Syntax und Funktionen

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

• Einfache Tabelle: Verwenden Sie das Pipe-Zeichen (|), um Spalten zu trennen.

• Komplexe Tabelle: Verwenden Sie zusätzliche Formatierungsoptionen für das Styling und die Spanne.

Makros: AsciiDoc ermöglicht die Einbindung verschiedener Makros, um dynamische Inhalte, die Einbindung externer Dateien und mehr zu handhaben. Das Beste daran: Sie behalten die Originaldatei an ihrem Platz und verweisen nur auf sie. Daher werden keine Kopien benötigt und alle Aktualisierungen sind in Ihrem Dokument sichtbar.

• Includes: include::filename.adoc[]

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

• Attribute Definition: :attribute_name: Text

• Attribute Reference: {attribute_name} -> In der Vorschau und beim Export wird der Text aus der Definition angezeigt (in diesem Fall „Text“)

Neben der Verwendung als Variable können Sie mit Attributen Ihr Dokument weiter anpassen. Zum Beispiel durch Hinzufügen von Seitenzahlen in der PDF-Ausgabe oder durch Einfügen eines Inhaltsverzeichnisses.

Verwendung von AsciiDoc mit CSS-Stylesheets

Eine der Stärken von AsciiDoc ist seine Fähigkeit, mit CSS gestylt 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.

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

---

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

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.

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

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, IntelliJ IDEA und Atom, 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

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.

---

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:

• AsciiDoc Syntax Quick Reference

• Create your First Documentation - Quick Guide

• Stack Overflow

• Zulip

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.