AsciiDoc | Arbeiten mit adoc Studio

3.1. Was ist AsciiDoc?

AsciiDoc ist eine einfache Auszeichnungssprache, mit der Sie Texte in verschiedene Dokumentformate umwandeln können. Sie können AsciiDoc-Dateien in HTML, PDF, ePub und weitere Formate konvertieren.

Im Vergleich zu XML-basierten Formaten wie DocBook ist AsciiDoc leicht erlernbar und als reiner Text gut lesbar. Weitere Informationen finden Sie auf Wikipedia.

In diesem Kapitel verweisen Links auf die AsciiDoc-Dokumentation, die derzeit nur in Englisch verfügbar ist. Eine deutsche Übersetzung ist in Arbeit.

3.2. Text schreiben

Verfassen Sie Ihren Text im Editor wie gewohnt. Sie können alles als Fließtext hintereinander schreiben oder jeden Satz in eine neue Zeile setzen, das Erscheinungsbild bleibt gleich.

Erzeugen Sie einen neuen Absatz, indem Sie eine Leerzeile zwischen den Absätzen einfügen.

Damit lernen Sie einen zentralen AsciiDoc-Begriff kennen: den Block.

Ein Block ist jede zusammenhängende strukturelle Einheit auf Block-Ebene, nicht zu verwechseln mit einem typografischen „Textblock“.

Dazu gehören:

Absätze
Überschriften
Listen
Tabellen
Quellcode und andere Blöcke

Normaler Fließtext ist ein Absatzblock und muss nicht explizit als Block deklariert werden, er ist es implizit.

Die Präambel

Beginnt ein Dokument vor dem ersten Abschnitt mit Text, wird der erste Absatz als Präambel oder Abstrakt bezeichnet. Er erscheint automatisch etwas größer als der reguläre Text und dient häufig als Einleitung.

Möchten Sie weitere Absätze vergrößern, setzen Sie [.lead] davor.

Eine Formatierung wie im Abstrakt oder Präambel mitten im Text einbinden

[.lead]
Dieser Absatz wird etwas größer als die anderen Absätze dargestellt. 
Mit dem Produktstil „Optima“ erhält der Absatz ein _Initial_ einen Großbuchstaben als dekoratives Element.

Ergebnis:

Dieser Absatz wird etwas größer als die anderen Absätze dargestellt. Mit dem Produktstil „Optima“ erhält der Absatz ein Initial einen Großbuchstaben als dekoratives Element.

Verhindern Sie den Effekt im ersten Absatz mit [.nolead] , damit Ihr Text direkt in der regulären Schriftgröße beginnt.

Mehr Informationen zu den Absätzen finden Sie in der AsciiDoc-Dokumentation.

3.3. Formatierungen

Die Gestaltung kommt in AsciiDoc aus den Cascading Style Sheets. Wie in jeder Auszeichnungssprache heben Sie im Editor nur einzelne Worte fett, kursiv oder anders hervor. Das Editor-Menü in adoc Studio bietet alle wichtigen Formatierungen für den schnellen Zugriff mit der Maus.

Das Editor-Menü in adoc Studio liefert Ihnen darüber hinaus alle wichtigen Formatierungen für den schnellen Zugriff.

Tabelle 6. Direkte Formatierungen im Editor-Menü
Befehl	Tastaturkurzbefehl	Auszeichnung im Text	Ergebnis in der Vorschau
Fett	`⌘`+`B`	fett	fett
Kursiv	`⌘`+`I`	_kursiv_	Kursiv
Markiert	`⌘`+`#`	#markiert#	markiert
Feste Laufweite	`⇧`+`⌘`+`#`	`feste Laufweite`	`feste Laufweite`
Unterstrichen	`⌘`+`U`	[.underline]#unterstrichen#	unterstrichen
Durchgestrichen	`⇧`+`⌘`+`X`	[.line-through]#durchgestrichen#	durchgestrichen
Überstrichen	`⌥`+`⇧`+`⌘`+`X`	[.overline]#überstrichen#	überstrichen
Hochgestellt	`⌥`+`⇧`+`⌘`+`+`	^hochgestellt^	^hochgestellt
Tiefgestellt	`⌥`+`⇧`+`⌘`+`-`	~tiefgestellt~	_tiefgestellt

AsciiDoc kann noch viel mehr.
Kombinieren Sie verschiedene Auszeichnungen nach Belieben.

**##Super##cali[underline]##fragilist__isch##[red]##expialige__tisch##** 😀

Ergebnis in der Vorschau:

Supercalifragilistischexpialigetisch 😀

Mehr Informationen zu den Formatierungen im Text finden Sie in der AsciiDoc-Dokumentation.

3.4. Überschriften

Überschriften legen Sie über die Anzahl der = fest, um die jeweilige Ebene zu bestimmen. Im Quelltext sehen alle Überschriften folgendermaßen aus:

= Dokumenttitel
== Überschrift 1
=== Überschrift 2
==== Überschrift 3
===== Überschrift 4
====== Überschrift 5

Weitere Überschriften

Reichen die sechs Überschriftenebenen plus Dokumenttitel nicht aus, setzen Sie vor der Zeile ein `. als Absatzüberschrift:

.Weitere Überschriften

Mehr Informationen zu den Überschriftsebenen finden Sie in der AsciiDoc-Dokumentation.

3.5. Der Dokumentkopf

Der Dokumenttitel, markiert mit =, definiert einen zentralen Bereich jedes Dokuments: den Dokumentkopf.

Um von Anfang an eine klare Struktur zu etablieren, sollte jedes AsciiDoc-Dokument mit einem Dokumentkopf beginnen. Er enthält:

den Dokumenttitel.
Angaben zu Autor und Überarbeitung.
dokumentweite Attribute.
weitere Metadaten.

Mehr Informationen zu den Dokumentkopf finden Sie in der AsciiDoc-Dokumentation.

Obwohl die AsciiDoc-Dokumentation empfiehlt, den Titel (= Dokumenttitel) als erste Zeile zu setzen, zeigt unsere Praxis einen effizienteren Weg.

In Dokumenten mit zahlreichen Attributen, wie in diesem Handbuch, werden alle Attribute vor dem Dokumenttitel gesetzt, nicht danach.

Das Ergebnis bleibt dasselbe, die Übersichtlichkeit steigt jedoch deutlich, besonders bei den Funktionen von adoc Studio wieSammeldokumente und die Übersetzungsunterstützung.

Beispiel für einen alternativen Dokumentkopf mit identischer Ausgabe

// Kommentare werden ignoriert 1
= Dokumenttitel
Felix Fleissig <support@adoc-studio.app> 2
:description: The document's description.
:sectanchors:
:url-repo: https://my-git-repo.com
5
Hier folgt das Dokument …

// Kommentare werden ignoriert 1

:author: Felix Fleissig <support@adoc-studio.app> 3
4
:description: The document's description.
:sectanchors:
4
:url-repo: https://my-git-repo.com
4
= Dokumenttitel
5
Hier folgt das Dokument …

1	Kommentare sind nur im Editor sichtbar.
2	Der Autor wird automatisch durch die Autorenzeile gesetzt.
3	Der Autor wird durch ein Attribut gesetzt.
4	Es sind beliebig viele Leerzeilen erlaubt
5	Eine Leerzeile nach dem Dokumenttitel trennt den Dokumentkopf vom Inhalt

Der Vorteil zeigt sich sofort: Der Dokumentkopf ist klar strukturiert und die Übersichtlichkeit steigt deutlich.

Untertitel zum Dokumenttitel

Ein Dokument darf nur einen Titel = haben. Ausnahme ist der Dokumenttyp Buch, aber dazu später mehr.

Einem Dokumenttitel können Sie optional einen Untertitel hinzufügen. Standardmäßig trennt ein : den Untertitel vom Titel. Alternativ legen Sie per [separator=ZEICHENKETTE]vor dem Titel oder als Attribut im Dokumentkopf (:title-separator: ZEICHENKETTE) eine eigene Trennzeichenkette fest.

Asciidoctor zeigt Untertitel nur im PDF an, nicht im HTML.
In adoc Studio funktionieren Untertitel in beiden Formaten.

3.6. Inhaltsverzeichnis

Sobald Sie Überschriften verwenden, empfiehlt sich ein Inhaltsverzeichnis. In adoc Studio erstellen Sie es ganz einfach: Legen Sie Ihre Überschriften an und fügen Sie :toc: in den Dokumentkopf ein. adoc Studio erzeugt das Inhaltsverzeichnis automatisch.

Standardmäßig:

enthält es zwei Überschriftenebenen
steht es zwischen Dokumenttitel und Text
aktualisiert es sich während des Schreibens automatisch

Das Attribut :toc: unterstützt zusätzliche Parameter:

left – positioniert das Inhaltsverzeichnis links neben dem Text.
right – positioniert es rechts neben dem Text.
preamble– fügt es nach der Präambel ein.
macro– fügt es über das Makro toc::[] an einer frei gewählten Stelle ein.
auto– entspricht der Verwendung ohne Parameter.

Mit der Zahl hinter :toclevels: legen Sie fest, wie viele Überschriftenebenen das Inhaltsverzeichnis anzeigen soll, zum Beispiel :toclevels: 3.

Definieren Sie dieses Attribut im Dokumentkopf. Standardmäßig zeigt das Inhaltsverzeichnis zwei Ebenen an.

Mehr Informationen zu Inhaltsverzeichnissen finden Sie in der AsciiDoc-Dokumentation.

3.7. Links

Sie können zwei Arten von Links verwenden:

Hyperlinks ins Internet.
Querverweise innerhalb des Dokuments.

Hyperlinks ins Internet

Der einfachste Link besteht aus einer ausgeschriebenen Adresse, zum Beispiel: https://www.adoc-studio.app. In der Vorschau wird die Adresse automatisch aktiv und lässt sich anklicken und öffnet sich im Webbrowser. Unterstützt werden die gängigsten URL-Schemas:

http
https
ftp
irc
mailto

Alternativ geben Sie Links als Makro an: https://www.adoc-studio.app[]

Zwischen den eckigen Klammern können Sie optional einen Linktext angeben. Dieser Text ersetzt dann die angezeigte URL:

Eingabe → https://www.adoc-studio.app[{app-name}-Webseite]
Ausgabe → adoc Studio-Webseite

Mehr Informationen zu Hyperlinks finden Sie in der AsciiDoc-Dokumentation.

Querverweise im Dokument

Mit einem Querverweis springen Sie zu einer anderen Stelle im selben Dokument. Das funktioniert sowohl in Einzel- als auch in Sammeldokumenten.

<<Referenz>>

Ein Querverweis verweist auf einen sogenannten Anker.

Ein Anker ist ein benannter Zielpunkt im Dokument. Er funktioniert ähnlich wie eine HTML-ID. Ein Anker ist nicht sichtbar, sondern markiert lediglich eine Position.

Zwar erzeugt AsciiDoc automatisch Anker für Überschriften, dennoch sollten Sie diese möglichst nicht verwenden. Ändern Sie eine Überschrift, wird ein automatischer Anker ebenfalls geändert und bestehende Verweise funktionieren dann nicht mehr.

Setzen Sie daher besser einen eigenen Anker vor die Überschrift:

[#ein_anker] 
== Eine Überschrift

Im Text verweisen Sie so darauf:

<<ein_anker>>

Im fertigen Dokument erscheint automatisch der Titel der Überschrift. Alternativ geben Sie einen eigenen Linktext an:

<<ein_anker, Springe hier hin>>

Mehr Informationen zu Querverweisen finden Sie in der AsciiDoc-Dokumentation.

Fußnoten

Asciidoctor zeigt Fußnoten standardmäßig als Endnoten an. adoc Studio unterstützt sowohl footnote als auch endnote.

Mit dem Attribut :footnotes-position: steuern Sie die Position und stellen die Kompatibilität mit bestehenden Dokumenten sicher.

Das Makro footnote:[] generiert automatisch Fußnoten. In der Vorschau und dem Export wird der Text der Fußnote dann in eckigen Klammern hinter dem Makro eingefügt:

Mein Text.footnote:[Hier ist der Text der Fußnote] 1

1	Da in AsciiDoc eine Fußnote direkt an den Text angehängt, ist sie im Editor manchmal schwer zu erkennen. Eine farbliche Hervorhebung hilft bei der Orientierung.

Die Ausgabe hängt vom Format ab:

HTML: Alle Fuß- und Endnoten erscheinen am Ende des Dokuments, da HTML-Seiten nicht paginiert sind.
PDF und Webseite: Fußnoten erscheinen auf der Seite, auf der sie definiert wurden. Endnoten stehen immer am Dokumentende.

Mehr Informationen zu Fußnoten finden Sie in der AsciiDoc-Dokumentation.

Bibliographie

AsciiDoc verwendet für Literaturangaben ein Bibliographie-Verzeichnis, ähnlich wie bei Endnoten. Wenn Sie keine externe Bibliographie-Datenbank nutzen, erstellen Sie die Einträge als speziell formatierte Liste. Legen Sie am Ende des Dokuments einen Abschnitt mit der Klasse [bibliography] an.

Fügen Sie darunter eine unsortierte Liste ein. Kennzeichnen Sie jeden Eintrag mit drei eckigen Klammern und einer eindeutigen ID, zum Beispiel: [[[buch-id]]].

Beispiel:

[bibliography]
== Literatur

* [[[blome-cherif-merlin]]] Frank Blome, Antoni Nadir Cherif. Projektmanagement mit Merlin – Das offizielle Handbuch. Carl Hanser Verlag, München 2009. ISBN 978-3-446-41927-8. 
* [[[bruening-illenberger-pwpat]]] Brüning, Kai & Illenberger, Frank. Method and system for syncing data structures. US20160055226A1, n.d. https://patents.google.com/patent/US20160055226A1/en.

Im Text verweisen Sie mit einem einfach Link darauf: <<blome-cherif-merlin>>.

Mehr Informationen zu Bibliographie finden Sie in der AsciiDoc-Dokumentation.

3.8. Bilder einfügen

In der Einführung wurde kurz gezeigt, wie Bilder und ihre Pfade funktionieren. Im Folgenden wird beschrieben, wie Bilder direkt in den AsciiDoc-Text eingebunden werden.

Bilder lassen sich auf zwei Arten einfügen, als Blockbild oder als Inline-Bild im Fließtext.

Blockbilder

Fügen Sie ein Bild als Blockbild in einer eigenen Zeile ein mit:

image::bild.png[]

Optionen passen Sie direkt in den Klammern an. Wichtige Parameter sind:

width – legt die Breite des Bildes fest.
align – bestimmt die Ausrichtung des Bildes.
float – steuert den Textfluss (Umfluss) um das Bild.

Das Vervollständigungsmenü von adoc Studio hilft Ihnen dabei, wie im Beispiel "Beispiel: Ein Bild im Text einbinden" gezeigt.

Inline-Bilder

Inline-Bilder stehen im Fließtext und verwenden die gleiche Syntax wie Blockbilder, allerdings mit nur einem Doppelpunkt :

image:bild.png[]

Beispiel im Satz:

Drücken Sie bitte image:reload.svg[], um die Seite neu zu laden.

Das Ergebnis in der Vorschau:
Drücken Sie bitte , um die Seite neu zu laden.

Mehrere Bilder nebeneinander fügen Sie so ein:

image:hello.jpg[width=80]
image:hello.jpg[width=120]
image:hello.jpg[width=170]

Die Bilder werden zentriert dargestellt und erhalten die angegebenen Breiten:

hello hello hello

Mehr Informationen zu Bildern finden Sie in der AsciiDoc-Dokumentation.

Symbole als Bilder

Symbole sind eine praktische Möglichkeit, Informationen visuell zu vermitteln und gleichzeitig unnötigen Text zu reduzieren. Sie eignen sich besonders, um Bedienungselemente zu illustrieren.

Damit Symbole in Hinweisen, bei den Nummern der Callouts oder im Icon-Makro angezeigt werden, muss das :icon:-Attribut gesetzt sein.

Bildbasierte Symbole

:icon: oder :icon: image

Die Symbole werden aus Bilddateien geladen, die im Verzeichnis liegen, das durch das iconsdir-Attribut angegeben ist.

Schriftbasierte Symbole

:icon: font

Die Symbole werden aus einer Symbolschriftart geladen, z.B.:

SF Symbols werden mit :icon-set: apple-Attribut gesetzt.

Sobald das Attribut gesetzt ist, erscheinen für alle Hinweise automatisch Symbole. Je nach Stil können diese auch exklusiv oder in unterschiedlichen Formaten dargestellt werden.

Mehr Informationen zu Symbolen finden Sie in der AsciiDoc-Dokumentation.

Icons im Bild-Modus

Möchten Sie Symbole aus Bilddateien verwenden, muss zusätzlich das Attribut `:iconsdir: gesetzt werden:

:icons: image
:iconsdir: icons

Die Icons werden nach den gleichen Regeln im Projekt gesucht .

Möchten Sie einen anderen Dateityp verwenden, kann dieser über `:icontype: festgelegt werden. Beispiel:

:icons: image
:iconsdir: icons
:icontype: svg

Icons im Font-Modus

Eleganter ist die Verwendung von Schriftbibliotheken. Besonders die Sammlung der SF Symbols ist ein Alleinstellungsmerkmal von adoc Studio! Anwender, die Anleitungen für macOS, iOS, iPadOS oder visionOS schreiben, profitieren besonders davon.

SF Symbols werden einmalig im Dokumentkopf aktiviert:

:icons: font
:icon-set: apple

Für Font Awesome wählen Sie den gewünschten Stil:

far – ungefüllte Symbole
fas – gefüllte Symbole
fab – Markensymbole

Beispiel:

:icons: font
:icon-set: fas

Anschließend stehen – je nach verwendeter Schriftfamilie – verschiedenen Optionen zur Verfügung:

flip dreht die Darstellung horizontal oder vertical.
link setzt einen Hyperlink.
palette nutzt die Apple-Farbpalette (monochrome, hierarchical, multicolor).
role nutzt eine vordefinierte CSS-Rolle.
rotate dreht das Bild um 90°, 180° oder 270°.
size setzt die Größe von 1x bis 10x oder auf xs, lg xl, fw.
title setzt einen Titel.
weight setzt das Schriftgewicht von ultralight bis black.
window legt das Zielfenster fest, falls ein link definiert ist.

Mehr Informationen zu den Font Awesome-Symbolen finden Sie in der AsciiDoc-Dokumentation.

3.9. Listen

Eine ungeordnete Liste beginnen Sie mit einem *:

* Erster Punkt

Mit jedem weiteren Stern rücken Sie eine Ebene tiefer:

Ebene 1
- Ebene 2
  - Ebene 3
    
    Ebene 4
  - zurück auf Ebene 3
- zurück auf Ebene 2
zurück auf Ebene 1

Alternativ können Sie auch ein - verwenden:

eins
zwei
drei

Geordnete Listen

Geordnete Listen erstellen Sie mit einem Punkt . :

eins
zwei
drei

Sie können auch stattdessen Zahlen angeben:

eins
zwei
drei
In der Vorschau und im Export erfolgt die Nummerierung automatisch korrekt. Im Beispiel oben würde statt der „7.“ (nur im Editor zu sehen) die „4.“ in der Vorschau erscheinen.

In adoc Studio wird die Nummerierung immer automatisch erstellt.

Mehrstufige geordnete Listen

Für verschachtelte Nummerierungen gilt dasselbe Prinzip wie bei ungeordneten Listen:

Schritt 1
1. Schritt 1 a
2. Schritt 1 b
Schritt 2
Schritt 3

Welche Nummerierungsart auf einer Ebene verwendet wird, hängt letztlich vom jeweiligen Produktstil ab.

Checklisten

Checklisten sind ebenfalls möglich:

zu erledigen
erledigt
auch erledigt

Damit die Checklisten entsprechend dem Produktstil dargestellt werden, muss zuvor das Attribut :icons: font gesetzt sein.

Mehr Informationen zu Listen finden Sie in der AsciiDoc-Dokumentation.

3.10. Blockelemente

Blockelemente – kurz Blöcke – sind äußerst vielseitig in AsciiDoc. Es gibt zahlreiche Einsatzmöglichkeiten und Darstellungsformen.

Typische Anwendungsfälle sind:

Hinweise
Randnotizen
Quellcode und Listings
Gleichungen
Durchreiche-Blöcke (Passthrough)
Zitate

Blöcke können in unterschiedlichen Formen notiert werden:

als Kurzform (meist einzeilig).
als Absatz über mehrere Zeilen.
als mehrteiliger Block mit mehreren Absätzen und Leerzeilen.

Die folgenden Beispiele zeigen das Konzept am Beispiel eines Zitats.

Zitat (Kurzform)

So schreiben Sie ein Zitat in Kurzform:

.Titel
"Text"
-- Autor,Werk

Zitat (als Absatz)

So notieren Sie ein Zitat als Absatz:

.Titel
[quote,Autor,Werk]
Text

Zitat (mehrere Absätze)

Für ein Zitat mit mehreren Absätzen verwenden Sie Blockbegrenzer:

.Titel
[quote,Autor,Werk]
____
Text
____

Wenn sie den adoc Coach für das Anlegen von Blöcken verwenden, sind einige Texte als Platzhalter formatiert. Ist ein Platzhalter selektiert und blau markiert, ersetzen Sie ihn einfach.

. Möchten Sie den Platzhalter nicht verwenden, drücken Sie Enter oder Löschen.

Ein Block steht immer zwischen zwei Begrenzern mit jeweils vier identischen Zeichen. Diese definieren Blockanfang und Blockende.

Es gibt verschiedene mögliche Begrenzer, wie im folgenden Beispiel:

Lernen ist Erfahrung. Alles andere ist einfach nur Information.

— Albert Einstein

Mehr Informationen zu Text- und anderen Blöcken finden Sie in der AsciiDoc-Dokumentation.

Quellcode mit Kommentare

Mit dem Source-Block dokumentieren Sie Quellcode strukturiert und übersichtlich. Zwischen zwei Zeilen mit ---- setzt adoc Studio die Formatierungsregeln außer Kraft. Innerhalb dieses Bereichs schreiben Sie unformatierten Text. Hier steht einfacher, nicht formatierter Text.

Geben Sie mit source an, dass es sich um Quellcode handelt. Optional definieren Sie zusätzlich die Sprache, zum Beispiel: [source, c].

Für das Syntax-Highlighting verwendet adoc Studio die Bibliothek highlightjs.org, die derzeit über 190 Programmiersprachen unterstützt.

Das AsciiDoc-Attribut :source-highlighter: highlight.js ist in adoc Studio seit v3 automatisch gesetzt.

Eingabe

.Brian Kernighan: Hello World
[source,c]
----
#import <standardio.h>  
int main()
{
  printf ("hello, world\n");
}
----

Ergebnis

Brian Kernighan: Hello World

#import <standardio.h>

int main()
{
   printf ("hello, world\n");
}

Mehr Informationen zu Quelltexten finden Sie in der AsciiDoc-Dokumentation.

Wenn Sie Quellcode erläutern möchten, verwenden Sie sogenannte callouts. Setzen Sie dazu am Ende einer Zeile ein Kommentarzeichen gefolgt von einer Ziffer in spitzen Klammern.

Unterhalb des Source-Blocks wiederholen Sie die Ziffern mit der jeweiligen Erklärung.

Eine Zeile Quelltext 1
Eine Zeile Quelltext 2
Eine Zeile Quelltext 3
Eine Zeile Quelltext 4

1	Kommentar im C -Stil.
2	Kommentar für Ruby , Python , Perl usw.
3	Kommentar für Clojure .
4	Kommentar für XML - oder SGML -Sprachen wie HTML .

Mehr Informationen zu Kommentaren finden Sie in der AsciiDoc-Dokumentation.

Hinweise

Mit Hinweisen unterbrechen Sie bewusst den Textfluss und lenken die Aufmerksamkeit auf wichtige Informationen.

Setzen Sie am Anfang Ihres Dokuments das Attribut :icons: font nur so werden die Symbole korrekt angezeigt.

Hinweise erscheinen in unterschiedlichen Stilen mit passenden Symbolen:

NOTE kennzeichnet ergänzende Hinweise.

TIP gibt einen nützlichen Hinweis oder eine besondere Empfehlung.

WARNING warnt vor einer möglichen Gefahr.

CAUTION weist auf eine mögliche Fehlerquelle hin.

IMPORTANT kennzeichnet eine besonders wichtige Information.

Nachfolgend ein Hinweis.

Mehr Informationen zu Hinweisen finden Sie in der AsciiDoc-Dokumentation.

Gleichungen und Formeln (STEM)

STEM steht für _Science, Technology, Engineering & Mathematics (im Deutschen: MINT - Mathematik, Informatik, Naturwissenschaften und Technik). In der technischen Dokumentation beschreibt dieser Begriff die Darstellung von Formeln und Gleichungen.

AsciiDoc unterstützt mathematische Ausdrücke mithilfe von \(\mathrm{\LaTeX}\) in der Variante von asciimath oder latexmath.

Inline verwenden Sie zum Beispiel (latexmath:[\mathrm{\LaTeX}])

Oder Sie verwenden einen Block:

[latexmath] 
++++ 
Life = \huge \int_ {birth}^{death} \normalsize \frac{happiness}{time} \Delta time
++++

\[Life = \huge \int_ {birth}^{death} \normalsize \frac{happiness}{time} \Delta time\]

Alternativ nutzen Sie die vereinfachte asciimath-Schreibweise:

[asciimath]
++++
sqrt(4) = 2
++++

\{sqrt(4) = 2\}

Mehr Informationen zu STEM finden Sie in der AsciiDoc-Dokumentation.

Randnotizen

Dieser Blocktyp ist ein gutes Beispiel für das Zusammenwirken von Text und Gestaltung. Eine Randnotiz (engl. Sidebar) erscheint als hervorgehobener Block im Text. Dieser Text:

 [sidebar]
 Dieser Text wird als Randnotiz hervorgehoben.

Ergibt diesen Block:

Dieser Text wird als Randnotiz hervorgehoben.

Wenn Sie das Beispiel mit dem Stil „Modern“ nutzen und die Vorschau auf PDF stellen, bekommt der Begriff Randnotiz plötzlich seinen Sinn. So wird die Randnotiz zu einer echten Notiz am Rand.

Durchreiche-Blöcke (Passthrough)

Wenn Sie Inhalte unverändert in das erzeugte HTML übernehmen möchten, verwenden Sie einen Durchreiche-Block.

Damit geben Sie Text oder Code – etwa SVG – direkt aus.

:my_color: red

[subs=attributes]
++++
<svg width="100" height="100">
  <rect width="100" height="100" fill="{my_color}" />
</svg>
++++

So ändern Sie die Farbe bequem über ein Attribut:

3.11. Tabellen

Mit Tabellen lassen sich Inhalte strukturiert und übersichtlich darstellen. Bereits mit wenigen Zeichen erstellen Sie einfache tabellarische Layouts.

Einfache Tabelle

Beginnen Sie mit einer minimalen Tabelle:

|===
| Eins | Zwei | Drei
|===

Das Ergebnis:

Eins

Zwei

Drei

Tabelle mit mehreren Zeilen

Ergänzen Sie eine einfache Tabelle mit weitere Zeilen:

|===
| Eins | Zwei | Drei
| Vier | Fünf | Sechs
|===

Das Ergebnis:

Eins

Zwei

Drei

Vier

Fünf

Sechs

Tabelle mit Kopfzeile

Eine Kopfzeile erzeugen Sie, indem Sie nach der ersten Zeile eine Leerzeile einfügen:

|===
| Titel 1 | Titel 2 | Titel 3

| Eins | Zwei | Drei
| Vier | Fünf | Sechs
|===

Das Ergebnis:

Titel 1	Titel 2	Titel 3
Eins	Zwei	Drei
Vier	Fünf	Sechs

Titel 1

Titel 2

Titel 3

Eins

Zwei

Drei

Vier

Fünf

Sechs

Erweiterte Tabellenfunktionen

AsciiDoc bietet umfangreiche Möglichkeiten zur Formatierung von Tabellenzellen. Das folgende Beispiel orientiert sich an der offiziellen Dokumentation:

|===
|Spalte 1 |Spalte 2

2*>m|Dieser Inhalt wird über zwei Spalten (2*) dupliziert und am rechten Rand der Zelle ausgerichtet (>).

Der Text wird mit einer Monospace-Schriftart (`m`) gerendert.

.3+^.>s|Diese Zelle erstreckt sich über 3 Zeilen (`3+`).
Der Inhalt wird horizontal zentriert (`+^+`), vertikal am unteren Rand der Zelle ausgerichtet (`.>`) und als stark formatiert (`s`) dargestellt.
e|Dieser Inhalt wird kursiv dargestellt (`e`).

m|Dieser Inhalt wird mit einer Monospace-Schriftart dargestellt (m).

s|Dieser *Inhalt* ist fett (`s`), außer dem Wort _Inhalt_.| Ende.
|===

Das Ergebnis:

Spalte 1 Spalte 2

Spalte 1	Spalte 2
`Dieser Inhalt wird über zwei Spalten (2*) dupliziert und am rechten Rand der Zelle ausgerichtet (>).` `Der Text wird mit einer Monospace-Schriftart (m) gerendert.`	Diese Zelle erstreckt sich über 3 Zeilen (`3+`). Der Inhalt wird horizontal zentriert (`^`), vertikal am unteren Rand der Zelle ausgerichtet (`.>`) und als stark formatiert (`s`) dargestellt.
Dieser Inhalt wird kursiv dargestellt (`e`).
`Dieser Inhalt wird mit einer Monospace-Schriftart dargestellt (m).`
Dieser Inhalt** ist fett (`s`), außer dem Wort Inhalt.**	Ende.

Dieser Inhalt wird über zwei Spalten (2*) dupliziert und am rechten Rand der Zelle ausgerichtet (>).

Der Text wird mit einer Monospace-Schriftart (m) gerendert.

Diese Zelle erstreckt sich über 3 Zeilen (3+). Der Inhalt wird horizontal zentriert (^), vertikal am unteren Rand der Zelle ausgerichtet (.>) und als stark formatiert (s) dargestellt.

Dieser Inhalt wird kursiv dargestellt (e).

Dieser Inhalt wird mit einer Monospace-Schriftart dargestellt (m).

Dieser Inhalt ist fett (s), außer dem Wort Inhalt.

Ende.

Mehr Informationen zu Tabellen finden Sie in der AsciiDoc-Dokumentation.

3.12. Benutzerschnittstelle

In der technischen Dokumentation gehören Beschreibungen der grafischen Benutzeroberfläche (GUI) – kurz UI (User Interface) – zum Alltag.

Dabei spielen vor allem drei Bereiche eine zentrale Rolle:

Tastaturkurzbefehle

Mit dem kbd:[]- Makro stellen Sie Tastaturkurzbefehle dar.

Beispiel → ⌘+S führt schnell zum Sichern des Dokuments.

Eine Besonderheit des kbd:[]-Makros zeigt sich bei der Nutzung der Pfeiltasten (↑ ↓ ← →) in diesem Dokument.

Menüs

Mit dem menu:[]-Makro lassen sich Menüpfade darstellen, zum Beispiel:

Ablage Export Produkte …

Schaltflächen

Für Schaltflächen steht das btn:[]-Makro zur Verfügung.

Damit wird eine Schaltfläche wie OK dargestellt.

Mehr Informationen zu UI-Makros finden Sie in der AsciiDoc-Dokumentation.

Gerade auf der Apple-Plattform ist bei den UI-Makros der Einsatz der SF-Symbols besonders sinnvoll, da sich Systemelemente so authentisch und plattformkonform darstellen lassen.

3.13. Kommentare

Im Quelltext dienen Kommentare dazu, Anmerkungen, Notizen oder Aufgaben direkt im Dokument zu hinterlegen. Sie helfen dabei, Hintergründe zu erläutern, Entscheidungen zu dokumentieren oder Gedankengänge nachvollziehbar zu machen. Kommentare sind ausschließlich im Editor sichtbar. In derVorschau und in den Exporten erscheinen sie nicht.

Einzelne Zeilen kommentieren

Beginnen Sie eine Zeile mit //, um den nachfolgenden Text als Kommentar zu kennzeichnen:

// Dieser Text ist ein Kommentar und wird nicht in der Vorschau oder dem Export angezeigt.

Ganze Abschnitte auskommentieren

Um größere Textbereiche zu kommentieren, verwenden Sie am Anfang und Ende des Blocks jeweils ////:

Warum Kommentare verwenden?

Auch wenn Kommentare im fertigen Dokument nicht erscheinen, sind sie für die Arbeit im Quelltext sehr hilfreich. Typische Einsatzbereiche sind::

// TODO:: – offene Aufgaben wie Optimierungen, Verbesserungen oder Korrekturen.
Hinweise zur Formatierung.
Begründungen für bestimmte Inhalte oder Entscheidungen.
Interne Versionshinweise.
Anmerkungen für Lektorat oder fachliche Prüfung.
Zusätzliche Kontextinformationen, die nur im Editor benötigt werden.

Mehr Informationen zu Kommentaren finden Sie in der AsciiDoc-Dokumentation.

3.14. Attribute

Setzen Sie Attribute gezielt ein, um Ihre Dokumentation flexibler und effizienter zu gestalten.

In adoc Studio erfüllen Attribute mehrere Funktionen. Sie ermöglichen:

Werte einmal zu definieren und im gesamten Dokument wiederzuverwenden
Dokumenteinstellungen zentral zu steuern und anzupassen

Medium wurde nicht gefunden.

Nutzung von Attributen als Variable

Wiederholen sich Begriffe, Versionsnummern, Produktnamen oder URLs im Text, definieren Sie diese einmal als Attribut.

So vermeiden Sie Tippfehler, reduzieren Redundanz und passen Änderungen zentral an.

Legen Sie ein Attribut an und verwenden Sie es anschließend im Dokument:

Beispiel 1. Nutzen Sie ein Attribut als Variable

Definition

:app-version: 1.2.3.4

Eingabe

Dieses Dokument basiert auf der Version {app-version}.

Ausgabe

Dieses Dokument basiert auf der Version 1.2.3.4.

Ändern Sie später den Wert des Attributs, aktualisieren sich alle Vorkommen automatisch.

Auch der Name adoc Studio wird in dieser Dokumentation über das Attribut {app-name} eingefügt.

Im Folgenden finden Sie weitere Attribute, die in diesem Dokument verwendet werden:

:app-name: adoc Studio
:lang: de
:url-website: https://www.adoc-studio.app
:url-roadmap: https://adoc-studio.canny.io 
:url-styles: https://forum.adoc-studio.app/t/css
:url-forum: https://forum.adoc-studio.app

In adoc Studio stehen mehrere Standardattribute bereit, die in den meisten Dokumenten verwendet werden. Tragen Sie diese zu Beginn des Dokuments im Dokumentkopf ein:

Autorenangaben (:author:)
Versionsangaben (:revnumber:, :revdate: und :revmark:)
Metadaten (:description:, :keywords:)

Ein Beispiel für den Dokumentkopf:

:author: Frank Blome
:revnumber: 1.0
:revdate: {docdate}
:description: Dieses Dokument führt Sie in die Arbeit mit {app-name} ein.
:keyword: {app-name}, AsciiDoc, Technische Dokumentation, Handbücher und mehr

Kürzen Sie einen Standardtitel folgendermaßen:

= Das Handbuch für {app-name}
Frank Blome <frank@projectwizards.net>
1.0, {docdate}

In diesem Fall übernimmt adoc Studio die folgenden Angaben automatisch aus den Zeilen direkt unter dem Dokumenttitel =:

:author:
:email:
:revnumber:
:revdate:

Verwenden Sie ein Attribut im Text mit der Syntax { Attributname }`.

Eingebaute Attribute

Mit eingebauten Attributen steuern Sie das Ausgabeverhalten Ihres Dokuments. Definieren Sie Attribute immer in einer eigenen Zeile und beginnen Sie am Zeilenanfang. Einige Attribute dürfen Sie überall im Dokument setzen, andere ausschließlich im Dokumentkopf.

Attribute erfüllen verschiedene Aufgaben:

Attribute:

greifen auf Dokumentinformationen zu
definieren Metadaten
aktivieren oder deaktivieren Funktionen
konfigurieren Funktionen
legen Speicherorte für Assets (z. B. Bilder) fest
speichern wiederverwendbare Inhalte

Syntax Beispiele:

Attribut setzen: :beta:.
Attribut mit Wert setzen: :beta-version: 23.
Attribut deaktivieren: (:!beta:) oder (:beta!:)

In adoc Studio greifen Sie komfortabel auf alle eingebauten Attribute über adoc Coach zu:

Drücken Sie am Zeilenanfang ESC und wählen Sie im Menü der Textvervollständigung den Eintrag Attribute. Die Liste zeigt alle verfügbaren eingebauten Attribute.

textmenu textmenuattributes

Mehr Informationen zu den eingebauten Attributen finden Sie in der AsciiDoc-Dokumentation.

Abweichungen zu Asciidoctor

adoc Studio orientiert sich am Standard von Asciidoctor, geht an einigen Stellen jedoch bewusst eigene Wege.

Bekannte Fehler aus Asciidoctor wurden nicht übernommen, sondern korrigiert. Darüber hinaus wurden ausgewählte Funktionen erweitert, um eine konsistentere und komfortablere Nutzung zu ermöglichen.

Details finden Sie im Kapitel Hinweise zur AsciiDoc-Kompatibilität.

Benutzerdefinierte Attribute

Benutzerdefinierte Attribute legen Sie selbst fest. Sie sind nicht durch AsciiDoc oder Erweiterungen reserviert.

Nutzen Sie diese Attribute, um:

wiederkehrende Texte zentral zu definieren
Bedingungen zu steuern
Inhalte mehrfach zu verwenden

Statt einen Produktnamen oder Hinweistext im gesamten Dokument zu wiederholen, definieren Sie ihn einmal als Attribut und referenzieren ihn anschließend. So arbeiten Sie effizient und vermeiden Redundanz.

Verwenden Sie für Attributnamen ausschließlich Kleinbuchstaben a,b,c… , Bindestriche - oder Unterstriche _. Andere Zeichen werden ignoriert.

Ein Beispiel, das in der Dokumentation für mp 32 Merlin Project regelmäßig genutzt wird:

:mp-mpe-features: https://www.projectwizards.net/merlin-project/features
:not-in-mpe: CAUTION: Diese Funktion ist in Merlin Project Express nicht enthalten. +
             Bitte vergleichen Sie Ihre Anforderungen mit der Tabelle +
             der {mp-mpe-features}[Funktionsvergleiche].

Wird zu:

Diese Funktion ist in Merlin Project Express nicht enthalten. Bitte vergleichen Sie Ihre Anforderungen mit der Tabelle der Funktionsvergleiche.

Diese Methode spart viel Arbeit: Der Text muss nicht ständig per Copy & Paste vervielfältigt werden. Änderungen führen Sie einmalig an einer Stelle durch, und alle Verwendungen im Dokument aktualisieren sich automatisch.

Mehr Informationen zu den Dokumentattributen finden Sie in der AsciiDoc-Dokumentation.

3.15. Bedingungen

Bedingungen steuern in adoc Studio, ob Text ausgegeben wird oder nicht. Man kann sich Direktiven also wie programmatische Steuerbefehle innerhalb des Dokuments vorstellen, die das Verhalten beeinflussen, ohne dass sie selbst im endgültigen Dokument sichtbar sind.

Verfügbare Direktiven:

ifdef: fügt Inhalt nur ein, wenn das angegebene Attribut existiert.
ifndef: fügt Inhalt nur ein, wenn das angegebene Attribut nicht existiert.
ifeval: fügt Inhalt nur ein, wenn der Ausdruck in den eckigen Klammern als wahr bewertet wird.

Beim Verarbeiten prüft der Prozessor die Bedingung anhand vorhandener Attribute oder deren Werte. Ist die Bedingung wahr, wird der Text ausgegeben; sonst wird er übersprungen.

Mehr Informationen zu den bedingten Anweisungen finden Sie in der AsciiDoc-Dokumentation.

3.16. Includes

AsciiDoc ermöglicht die Arbeit mit mehreren Dateien. Statt eine lange Datei zu erstellen, teilen Sie den Text in einzelne Kapitel auf.

In adoc Studio wurde im Abschnitt Der Projektnavigator ein eigenes Konzept für modulare Dokumente vorgestellt.

Wenn Autoren nicht alle Funktionen von adoc Studio nutzen, empfiehlt sich der include-Befehl. Damit fügen Sie Kapitel im AsciiDoc-Format nacheinander ein:

 include::kapitel-1.adoc[]
 include::kapitel-2.adoc[]
 include::kapitel-3.adoc[]

Includes in adoc Studio

Innerhalb von adoc Studio ist der include-Befehl besonders nützlich, wenn nicht alle Funktionen sofort dokumentiert werden. Dafür können Platzhalter eingesetzt werden. Beispiel: In der Dateiliste gibt es die Datei comingSoon.adoc. Damit sie nicht automatisch im Sammeldokument erscheint, wurde in den Dateiinformationen die entsprechende Checkbox deaktiviert. Weitere Details finden Sie hier.

Binden Sie die Platzhalter-Datei wie folgt ein:

:the_feature: wichtigen Funktionen 1
include::comingSoon.adoc[] 2

Die Ausgabe sieht so aus:

Die wichtigen Funktionen sind noch nicht beschrieben. Eine ausführliche Dokumentation wird so bald wie möglich bereitgestellt

Inhalt der Platzhalterdatei:

\ifdef::the_feature[] 3

CAUTION: Die _{the_feature}_ sind noch nicht beschrieben. 4 
Eine ausführliche Dokumentation wird so bald wie möglich zur Verfügung stehen.

:!the_feature: 5 

endif::[]

Erklärung:

1	Das Attribut `the_feature` erhält beim Einbinden der Datei einen Text, z. B. „wichtigen Funktionen“.
2	Die Datei `comingSoon.adoc` wird an der aktuellen Position eingefügt.
3	`ifdef` prüft, ob das Attribut Text enthält.
4	Ist das Attribut gesetzt, wird eine Warnung ausgegeben.
5	Danach leert `:!the_feature: das Attribut, damit es beim nächsten Durchlauf nicht erneut verwendet wird.

Mehr Informationen zu Includes finden Sie in der AsciiDoc-Dokumentation.

3.17. Docinfo

Mit Docinfo fügen Sie benutzerdefinierte Inhalte in den Kopf- oder Fußbereich des Ausgabedokuments ein. Der Konverter liest diese Inhalte aus sogenannten Docinfo-Dateien. Docinfo-Dateien erweitern die automatisch erzeugte Ausgabe und bieten praktische Möglichkeiten, zusätzliche Metadaten, Stylesheets oder Skripte einzufügen, die der Konverter nicht von Haus aus bereitstellt.

Mehr Informationen zu Docinfo finden Sie in der AsciiDoc-Dokumentation.

In adoc Studio sollten Sie das Attribut :docinfo: nicht direkt im Dokument setzen. Anders als Asciidoctor zeigt adoc Studio nicht nur HTML, sondern auch PDF in der Vorschau an. Da das PDF auf HTML basiert, interpretiert adoc Studio das Attribut korrekt, die Ausgabe kann jedoch optisch störend wirken. Um das zu vermeiden, stehen zwei Varianten zur Verfügung:

1 Quelltext: Fügen Sie den folgenden Codeblock in den Dokumentkopf ein:

ifdef::filetype-webseite[]
:docinfo: shared
endif::[]

2 In den Produkteinstellungen: Sie erstellen ein Produkt für die Ausgabe der Webseite oder von HTML. Fügen Sie in der Attributliste die Werte :docinfo: und shared hinzu.

3. AsciiDoc

3.1. Was ist AsciiDoc?

3.2. Text schreiben

Die Präambel

3.3. Formatierungen

3.4. Überschriften

3.5. Der Dokumentkopf

Untertitel zum Dokumenttitel

3.6. Inhaltsverzeichnis

3.7. Links

Hyperlinks ins Internet

Querverweise im Dokument

Fußnoten

Bibliographie

3.8. Bilder einfügen

Blockbilder

Inline-Bilder

Symbole als Bilder

Icons im Bild-Modus

Icons im Font-Modus

3.9. Listen

3.10. Blockelemente

Quellcode mit Kommentare

Eingabe

Ergebnis

Hinweise

Gleichungen und Formeln (STEM)

Randnotizen

Durchreiche-Blöcke (Passthrough)

3.11. Tabellen

3.12. Benutzerschnittstelle

3.13. Kommentare

3.14. Attribute

Nutzung von Attributen als Variable

Eingebaute Attribute

Abweichungen zu Asciidoctor

Benutzerdefinierte Attribute

3.15. Bedingungen

3.16. Includes

3.17. Docinfo