Asciidoc

Tags:
Categories:

Syntax

Da AsciiDoc als “Komplettsystem” angeboten wird, also Sprache inklusive Interpreter, gibt es eine zentrale Syntax. Varianten oder Dialekte wie bei Markdown gibt es bei AsciiDoc nicht.

Kommentare

AsciiDoc-Code kann - wie auch sonstiger Quelltext - kommentiert werden, d.h. Kommentare werden bei der Interpretation des Quelltextes (z.B. bei Umwandlung in ein PDF) nicht berücksichtigt. Damit können Dokumente bzw. Textteile kommentiert werden, oder Hinweise hinterlassen werden.


Das ist ein beliebiger Text in AsciiDoc.

// Diese Zeile wird nicht interpretiert.

Diese Zeile wird angezeigt.

Absätze/Zeilen

AsciiDoc benötigt keine speziellen Angaben für Zeilenschaltungen und Absätze. Der Text wird so umgesetzt wie er geschrieben wurde. Es ist jedoch möglich, eine Zeilenschaltung mit einem Plus-Symbol zu erzwingen. Alternativ kann auch das Attribut [%hardbreaks] vorgesetzt werden.


Dies ist Zeile Nummer Eins.
Dies ist Zeile Nummer Zwei.

Und nun noch ein Absatz.

Diese Zeile wird +
hart umgebrochen.

[%hardbreaks]
Diese Zeilen werden 
wie sie sind dargestellt.

Textformatierung

Fett, Kursiv, Hervorhebung, Code

Um Text fett, kursiv oder als Code darzustellen, gibt es zwei Möglichkeiten, bzw. wird unterschieden, ob es der zu formatierende Text allein steht oder sich in der Mitte eines Textes befindet.

Ein alleinstehendes Wort kann zwischen einzelne Sternchen, Unterstrich, Hashtag oder Gravis-Akzent.


Dieser Text ist *fett*.
Dieser Text ist _kursiv_.
Dieser Text ist `Code`.
Dieser Text ist #hervorgehoben#.

Will man einen Textteil in der Mitte formatieren, wird dies durch doppelte Sternchen, Unterstriche, Hashtag oder Gravis-Akzente erreicht. Würde dies mit einzelnen Zeichen versucht werden, würde die Formatierungsregel ignoriert werden.


Die "tt" in Mi**tt**ag sind fett.
Die "tt" in Mi*tt*ag sind nicht fett.

Die "tt" in Mi__tt__ag sind kursiv.
Die "tt" in Mi_tt_ag sind nicht kursiv.

Die "tt" in Mi``tt``ag sind Code.
Die "tt" in Mi`tt`ag sind nicht Code.

Die "tt" in Mi##tt##ag sind hervorgehoben.
Die "tt" in Mi#tt#ag sind nicht hervorgehoben.

Unterstrichen, Durchgestrichen

Um einen Text durch- bzw. zu unterstreichen, werden Hastags mit einem Attribut verwendet.


Dieser Text ist [.underline]#unterstrichen#.
Dieser Text ist [.line-through]#durchgestrichen#.

Superscript, Subscript und Smart Quotes

Mittels Superscript und Subscript können Textteile hoch- bzw. tiefgestellt werden. Dafür werden die Textteile zwischen einzelne Caret/Zirkumflex (Superscript) oder Tilde (Subscript) gesetzt.


Das ist ein ~Tief~punkt.
Das ist ein ^Höhe^punkt.

Hier ist der vervollständigte AsciiDoc-Text mit Inhalten für die leeren Kapitel (ab „Links“), basierend auf der offiziellen AsciiDoc-Syntax und gängigen Best Practices:

Gerne! Hier ist die überarbeitete Version deiner AsciiDoc-Dokumentation — nun mit kurzer, prägnanter Erklärung zu jedem Kapitel, bevor die Syntaxbeispiele kommen. So bleibt es übersichtlich, verständlich und nützlich für Einsteiger.

Erklärung:
AsciiDoc unterstützt sowohl externe Web-Links als auch interne Verweise innerhalb des Dokuments (Anker) sowie Links auf lokale Dateien. Die Syntax ist einfach und intuitiv — ideal für Dokumentationen, die verlinkt werden sollen.

https://www.asciidoc.org[AsciiDoc Website]

[[abschnitt1]]
== Erster Abschnitt

Siehe auch <<abschnitt1>>.

link:handbuch.pdf[Download Handbuch]

Dokumentenkopf

Erklärung:
Der Dokumentenkopf enthält Metadaten wie Titel, Autor, Datum und globale Attribute. Er ist optional, aber empfehlenswert für strukturierte Dokumente — besonders bei PDF- oder Buch-Exporten.

= Titel des Dokuments
Autor Name <autor@example.com>
:doctype: book
:author: Autor Name
:revdate: 2026-02-09

Automatisches Inhaltsverzeichnis

Erklärung:
Ein Inhaltsverzeichnis (TOC) wird automatisch generiert, sobald das Attribut :toc: gesetzt ist. Es kann links, rechts oder an einer beliebigen Stelle platziert werden — hilfreich für längere Dokumente.

:toc: left

= Haupttitel

== Kapitel 1
Inhalt...

== Kapitel 2
Weiterer Inhalt...

Includes

Erklärung:
Mit include:: kannst du externe AsciiDoc-Dateien oder Teile davon einbinden. Praktisch für wiederverwendbare Abschnitte (z. B. Fußzeilen, Hinweise, Kapitel).

include::kapitel1.adoc[]

include::../shared/footnotes.adoc[tag=abschnitt2]

Listen

Erklärung:
AsciiDoc unterstützt Aufzählungslisten (*), nummerierte Listen (.) und Definitionen (::). Die Einrückung bestimmt die Hierarchie — einfach und klar strukturiert.

Aufzählungslisten

* Punkt 1
* Punkt 2
  * Unterpunkt

Nummerierte Listen

. Erster Punkt
. Zweiter Punkt
.. Unterpunkt

Definitionen

Begriff::
  Definition des Begriffs.

Bilder

Erklärung:
Bilder werden mit image:: eingebunden. Du kannst Größe, Alternativtext und Skalierung steuern. Funktioniert in HTML, PDF und EPUB — je nach Backend.

image::logo.png[Logo, 200, 100]

image::diagramm.svg[Diagramm, scaledwidth=50%]

Audio

Erklärung:
Audio-Dateien (z. B. Sprachnachrichten) können direkt im Dokument eingebunden werden. Nützlich für Tutorials oder multimediale Dokumentationen.

audio::sprachnachricht.mp3[Sprachnachricht, autoplay]

Videos

Erklärung:
Videos werden mit video:: eingebunden. Du kannst Steuerungselemente wie autoplay, controls oder loop aktivieren — ideal für Anleitungen oder Präsentationen.

video::tutorial.mp4[Tutorial, width=640, height=360, autoplay, controls]

Tastatur, Button Menü Macros

Erklärung:
Mit kbd: und menu: kannst du Tastaturbefehle und Menüpfade klar hervorheben — besonders nützlich in Anleitungen oder Software-Dokumentationen.

Tastaturbefehle

Drücke kbd:[Strg+C] zum Kopieren.

Menübefehle

Gehe zu menu:Datei[Speichern unter...].

Sourcecode

Erklärung:
Codeblöcke mit Syntax-Highlighting werden mit [source] eingeleitet. Du kannst Sprachen wie Python, Bash oder HTML angeben — hilfreich für Entwicklerdokumentationen.

[source,python]
----
def hello():
    print("Hallo Welt")
----

Hinweise, Textblöcke

Erklärung:
Mit NOTE:, TIP:, WARNING: usw. kannst du wichtige Informationen hervorheben. Zitate mit ____ sind ideal für Zitate oder Zitate aus externen Quellen.

Hinweise

NOTE: Dies ist eine wichtige Information.

TIP: So geht’s schneller.

Zitate

____
„Das ist ein Zitat.“
— Autor
____

Tabellen

Erklärung:
Tabellen werden mit |=== definiert. Jede Zelle wird mit | getrennt. Du kannst Spaltenanzahl, Rahmen und Beschriftungen steuern — perfekt für Vergleiche oder Daten.

|===
| Spalte 1 | Spalte 2
| Wert A   | Wert B
| Wert C   | Wert D
|===

IDs, Rollen und Optionen

Erklärung:
Mit [[id]] setzt du Anker für interne Links. Mit [.rolle] kannst du CSS-Klassen zuweisen. Mit [%option] steuerst du Blockverhalten (z. B. unnummeriert).

IDs

[[kapitel2]]
== Kapitel 2

Rollen

[.hinweis]
Dieser Text hat eine Rolle.

Optionen

[%unnumbered]
== Dieser Abschnitt hat keine Nummer.

Attribute und Sonderzeichen

Erklärung:
Attribute (:name: wert) ermöglichen Wiederverwendung von Text oder Werten. Sonderzeichen wie + oder \\ müssen ggf. escaped werden, um nicht als Formatierung interpretiert zu werden.

Attribute

:version: 1.0

Die Version ist {version}.

Sonderzeichen

+ für Plus, \\ für Backslash, &#x27; für Apostroph.

Quellenverzeichnis

Erklärung:
Ein Literaturverzeichnis kann manuell oder über bibliography:: erstellt werden. Nützlich für wissenschaftliche oder referenzierte Dokumente.

[bibliography]
== Literatur

- Autor, Titel, Verlag, Jahr

Fussnoten

Erklärung:
Fußnoten werden mit footnote:[Text] oder [footnote:] eingefügt. Sie erscheinen am Ende des Dokuments oder der Seite — ideal für ergänzende Informationen.

Dies ist ein Satz mit einer Fußnote.footnote:[Das ist die Fußnote.]

Ein weiterer Satz mit [footnote:2]Fußnote 2[footnote:2].

Fazit

Vorteile

Ein grosser Vorteil von AsciiDoc ist sicher der grosse Funktionsumfang, mit dem sogar komplexe Dokumente mit Inhaltsverzeichnis und Quellenverzeichnis möglich sind. Auch die Include-Funktion und mögliche Kommentare erleichtern den Umgang mit viel Text und vielen Dateien, auch eine kollaborative Bearbeitung ist dadurch einfach. Da AsciiDoc nicht einfach nur eine Sprache, sondern auch ein Anwendung mitgeliefert wird, kann ohne grosse Umschweife produktiv damit gearbeitet werden. Ausser einem Texteditor für die Textdateien, wird sonst nichts weiteres benötigt.

Nachteile

AsciiDoc ist bei weitem nicht so stark verbreitet wie Markdown. Produktive Tools wie Notiz-Apps, Wikis oder Static Site Generatoren unterstützen nur selten AsciiDoc und wenn, dann meist nur mittels Plugins. Wer viel mit solchen Tools arbeitet, wird um die parallele Verwendung von Markdown und AsciiDoc nicht herumkommen.

Weiterführende Informationen

Literatur

Tools zur Anwendung von AsciiDoc

Texteditoren

Static Site Generatoren

Transformations-Werkzeuge