Das ist eine für den Ausdruck optimierte Ansicht des gesamten Kapitels inkl. Unterseiten. Druckvorgang starten.

Zur Standardansicht zurückkehren.

Docs-as-Code

1 - Asciidoc

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

2 - Markdown

Markdown ist sicher die verbreiteteste einfache Ausschreibungssprache.

Syntax

Basic-Syntax

Hierbei handelt es sich um die Grundbefehle, die Markdown bietet und grundsätzlich in jedem Tool funktionieren sollten.

Überschriften

Um Überschriften darzustellen, wird dem Überschriftentitel ein oder mehrere Hashtags vorgesetzt. Je nach Ebene.

# Überschrift 1

## Überschrift 2

### Überschrift 3

#### Überschrift 4

##### Überschrift 5

###### Überschrift 6

Hinweis: Am besten immer eine Leerzeile vor einer Überschrift einfügen, da ohne die Interpretationen nicht korrekt sein kann.

Absätze/Zeilen

Für Zeilenschaltungen und Absätze gibt es keine wirklichen Notationen, sondern hier wird der Text wie geschrieben angezeigt. Als Unterstützung kann für eine Zeilenschaltung ein doppeltes Leerzeichen an das Ende der Zeile eingefügt werden, oder alternativ auch der HTML-Tag <br>.


Erste Zeile mit zwei Leerzeichen am Schluss.  
Und nun die nächste Zeile.

Erste Zeile mit dem HTML-Tag am Schluss.<br>
Und nun die nächste Zeile.

Textformatierung

Standardmässig bietet Markdown die Möglichkeit, Text als Fett und/oder Kurisv darzustellen.

Um einen Text fett darzustellen, wird der entsprechende Textteil zwischen doppelten Sternen oder Underscores geschrieben.


Bei mir gibt es auch **fetten Text**.

Bei mir gibt es auch __fetten Text__.

Und hier gibt es **fetten Text** in der Mitte.

Um einen Text kursiv darzustellen, wird der entsprechende Textteil zwischen einfachen Sternen oder Underscores geschrieben.


Bei mir gibt es auch *kursiven Text*.

Bei mir gibt es auch _kursiven Text_.

Und hier gibt es *kursiven Text* in der Mitte.

Natürlich lässt sich es sich auch kombinieren:

Um einen Text fett darzustellen, wird der entsprechende Textteil zwischen doppelten Sternen oder Underscores geschrieben.


Bei mir gibt es  ***fetten und kursiven Text***.

Bei mir gibt es auch ___fetten und kursiven Text___.

Und hier gibt es ***fetten und kursiven Text*** in der Mitte.

Blockzitate

Um einen Text als Block zu zitieren, wird einfach ein “Grösser als”-Zeichen vor die Zeile gesetzt.


> Dieser Text befindet sich in einem Blockzitat.

Wenn das Blockzitat mehrere Zeilen umfassen soll, muss am Anfang jeder Zeile (auch bei leeren Zeilen) das “Grösser als”-Zeichen gesetzt werden.


> Dieser Text stellt die erste Zeile im Blockzitat dar.
> 
> Und hier gibt es die nächste Zeile.

Zitate können auch ineinander verschachtelt werden, hier wird in der nächsten Ebene bzw. zur Einrückung ein weiteres “Grösser als”-Zeichen gesetzt.


> Dieser Text befindet sich in einem Blockzitat.
> 
>> Dieser Text ist in der Verschachtelung.

Listen

Listen sind genauso einfach und werden einfach im Text geschrieben. Geht es in der Liste in eine weitere Ebene, wird dies durch eine Einrückung (4 Leerzeichen bzw. 1 Tab) ermöglicht.

Sortierte Liste

Sortierte Listen werden generiert, in dem einfach die entsprechende Zahl inklusive einem Punkt vor die Zeile gesetzt wird.


1. Erster Punkt
2. Zweiter Punkt
3. Dritter Punkt
    1. erste Einrückung
    2. zweite Einrückung
4. Vierter Punkt
Unsortierte Liste

Unsortierte Listen werden generiert, in dem einfach ein Bindestich vor die Zeile gesetzt wird.


- Erster Punkt
- Zweiter Punkt
- Dritter Punkt
    - erste Einrückung
    - zweite Einrückung
- Vierter Punkt

Um einen Link darzustellen, wird der Linktext in eckige Klammer gesetzt, gefolgt von der URL innerhalb von Rundklammern.

Sortierte Listen werden generiert, in dem einfach die entsprechende Zahl inklusive einem Punkt vor die Zeile gesetzt wird.


Meine liebste Suchmaschine ist [Swisscows](https://swisscows.com/de).

```markdown

Dem Link kann auch ein zusätzlicher Titel als Tooltip hinzugefügt werden.

```markdown

Meine liebste Suchmaschine ist [Swisscows](https://swisscows.com/de "Die schweizer Suchmaschine").

Als Kurzform kann eine URL auch einfach innerhalb von Spitzklammern geschrieben werden.


Meine liebste Suchmaschine ist <https://swisscows.com/de>.

Erweiterte Syntax

Gerne! Hier ist der ergänzte Abschnitt „Erweiterte Syntax“ mit präzisen, kurzen Erklärungen zu den fehlenden Punkten – im gleichen Stil wie deine Doku:

Erweiterte Syntax

Tabellen

Tabellen werden mit senkrechten Strichen (|) und Bindestrichen (-) definiert. Die erste Zeile enthält die Spaltenüberschriften, die zweite Zeile definiert die Ausrichtung (optional).

| Links ausgerichtet | Zentriert       | Rechts ausgerichtet |
| :--------------- | :-------------: | ------------------: |
| Zelle 1          | Zelle 2         | Zelle 3             |
| Zelle 4          | Zelle 5         | Zelle 6             |

Hinweis: Die Anzahl der Bindestriche in der Trennzeile ist beliebig, wichtig ist nur das : für die Ausrichtung.

Code Blocks

Für mehrzeiligen Code wird ein Code Block mit drei Backticks (```) oder mit vier Leerzeichen pro Zeile erstellt. Optional kann die Sprache angegeben werden, um Syntax-Highlighting zu aktivieren.

```python
def hello():
    print("Hello, World!")


---

#### Fussnoten

Fussnoten werden mit `[^Kennung]` im Text eingefügt und am Ende der Datei mit `[^Kennung]:` definiert.

```markdown
Hier steht ein Text mit einer Fussnote.[^1]

[^1]: Das ist die Erklärung zur Fussnote.

Hinweis: Nicht alle Markdown-Parser unterstützen Fussnoten – z. B. Hugo benötigt goldmark mit aktivierter Option.

IDs für Überschriften

Überschriften können mit einer ID versehen werden, um sie direkt zu verlinken (z. B. für Inhaltsverzeichnisse oder Ankerlinks).

## Überschrift mit ID {#meine-id}

[Link zur Überschrift](#meine-id)

Hinweis: In Hugo muss enableInlineShortcodes = true in der Konfiguration aktiviert sein.

Aufgabenlisten

Aufgabenlisten (Checklisten) werden mit - [ ] für ungeprüfte und - [x] für geprüfte Items erstellt.

- [x] Aufgabe erledigt
- [ ] Noch zu erledigen
- [ ] Wird später gemacht

Hinweis: Wird oft in GitHub, GitLab oder Notiz-Apps wie Obsidian genutzt.

Durchgestrichen

Durchgestrichener Text wird mit doppelten Tilden (~~) umschlossen.

Dieser Text ist ~~durchgestrichen~~.

Emojis

Emojis können direkt eingefügt werden (z. B. 😊) oder mit Shortcodes wie :smile: (je nach Parser).

Ich bin heute gut gelaunt 😊

Hinweis: In Hugo müssen Emojis explizit aktiviert werden (enableEmoji = true).

Hervorheben von Text

Einige Parser (z. B. Hugo mit Goldmark) unterstützen Hervorhebungen mit ==:

Dieser Text ist ==hervorgehoben==.

Hinweis: Nicht standardisiert – funktioniert nicht überall.

Sub-/Superscript

Subscript (H₂O) und Superscript (x²) werden mit ~ bzw. ^ dargestellt – aber nur in einigen Erweiterungen wie Pandoc oder Hugo mit speziellem Parser.

Wasser ist H~2~O.  
x^2^ ist x hoch 2.

Hinweis: Nicht Teil des CommonMark-Standards – Funktioniert z. B. in Hugo mit goldmark und aktivierter Option.

Falls du möchtest, kann ich dir auch ein vollständiges, aktualisiertes Markdown-Referenzdokument im Hugo-Format als Download bereitstellen – sag einfach Bescheid!

Verwendung

Markdown stellt kein eigenes System dar, sondern steht rein für eine offene und frei verfügbare Syntax. Man könnte Markdown auch mit einer integrierbaren Scriptsprache vergleichen. Dies ist sicher auch der Grund, wieso so viele Systeme Markdown unterstützen und die Sprache dadurch so vielseitig verwendbar ist.

Wiki-Systeme

Wiki-Systeme wie z.B. Mediawiki (auf dem Wikipedia aufbaut), dokuWiki oder integrierte Wiki-Funktionen wie z.B. bei Github oder Gitlab setzen standardmässig auf Markdown zur Verwaltung der Inhalte.

Wikis sind ja vor allem dazu da, Inhalte zu präsentieren, im Git-Bereich Dokumentationen zur angebotenen Software. Dank der einfachen Syntax können diese auch von Nicht-Techies erstellt und verwaltet werden.

Notizen

Auch die vielfach verfügbaren Notiz-Apps (oder teilweise auch Desktop-Wikis genannt) greifen für die Verwaltung der Inhalte auf Markdown zurück. Oft wird ein integrierter WYSIWYG-Editor zur Verfügung gestellt, jedoch verwendet dieser im Hintergrund Markdown. Es gibt auch meist die Möglichkeit, auf den Quelltext umzustellen und dort direkt zu bearbeiten. Beispiele hierfür sind Zim, Zettlr, QOwnNotes und Logseq im Open-Source-Bereich oder populäre Varianten wie Evernote, Obsidian oder Joplin.

Webseiten

Im Bereich Webseiten kommt Markdown in zweierlei Hinsicht vor. Zum einen bieten die bekannten Content Management Systeme (wie z.B. Wordpress und Drupal) oft Plugins/Module, um Inhalte in Markdown zu veröffentlichen. Aber neben CMS gibt es auch SSG, sogenannte Static Site Generatoren, wie z.B. Hugo oder Jekyll. Dazu gibt es noch ähnliche auf technische Dokumentationen spezialisierte Systeme wie MKDocs, Sphinx oder Docusaurus. Auch hier werden die ganzen Inhalte in Markdown angelegt und dann mittels Preprocessor in statische Webseiten umgewandelt, die dann veröffentlicht werden können.

Präsentationen/Kurse

Neben Webseiten, können mit Markdown auch Präsentationen erstellt werden. Jedoch handelt es sich hier nicht um Powerpoint-Präsentationen, sondern werden diese mittels Preprocessoren dynamisch in Webelemente umgewandelt. Beispiele sind hierfür Marp, remarkJS oder Cleaver. Speziell für Online-Kurse bietet sich die Markdown-Erweiterung LiaScript an.

Dokumente

Markdown fehlen sicher einige Funktionalitäten, wie sie eine Textverarbeitung wie MS Word oder LibreOffice Writer vorweisen können, doch reicht es für einfache Dokumente wie z.B. Briefe vollkommen aus.

Fazit

Vorteile

Markdown hat eine einfache und klare Syntax, ist demzufolge leicht zu erlernen. Markdown-Dokumente haben auch den Vorteil, dass sie selbst im Quelltext leicht lesbar sind. Sie sind also sowohl maschinen- als auch menschenlesbar. Letzteres dank der einfachen und geradlinigen Syntax ohne Overhead. Auch die grosse Verbreitung von Markdown, der Integration in so viele Tools spricht für sich.

Nachteile

Neben den klaren Vorteilen, gibt es aber leider auch negatives über Markdown zu berichten.

Markdown eignet sich sehr gut für Artikel und Notizen, die nicht so komplex aufgebaut sind. Möchte man mehr und z.B. grosse und komplexe Dokumente erstellen, wie z.B. ganze Bücher, fehlen nützliche Funktionen wie Inhaltsverzeichnis oder die Möglichkeit, Dateien mittels “Include” zu verschachteln.

Zwar gibt es mit CommonMark einen Markdown-Standard, doch die starke Verbreitung hat doch zu vielen “Dialekten” geführt, da viele Tools die Standard-Syntax durch eigene Befehle erweitern. Dadurch sind Markdown-Dokumente aus verschiedenen Systemen nicht zwingend untereinander kompatibel.

Weiterführende Informationen

Literatur

Tools zur Anwendung von Markdown

Desktop-Wikis

Texteditoren

Static Site Generatoren

Transformations-Werkzeuge