Code Blöcke

Code in Dokumenten darstellen

In der technischen Dokumentation sind Code-Beispiele essenziell. AsciiDoc bietet flexible Möglichkeiten, Code sowohl im Fließtext als auch in eigenen Blöcken darzustellen.

Für Inline-Code im Fließtext verwenden Sie Backticks:

Der Befehl `git status` zeigt den aktuellen Status an.

Ergebnis: Der Befehl git status zeigt den aktuellen Status an.

Code-Blöcke mit Syntax-Highlighting

Für mehrzeilige Code-Beispiele verwenden Sie einen Source-Block:

[source,python]
----
def greet(name):
    return f"Hallo, {name}!"

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

Das Ergebnis mit Syntax-Highlighting:

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

print(greet("Welt"))

Die wichtigsten Elemente:

  • [source,python] definiert die Programmiersprache für das Syntax-Highlighting.

  • ---- umschließt den Code-Block (vier Bindestriche).

adoc Studio unterstützt Highlighting für viele Sprachen: Python, JavaScript, Java, Swift, Ruby, SQL, HTML, CSS, Bash und viele mehr.

Callouts für Erklärungen

Mit Callouts können Sie einzelne Codezeilen direkt erklären:

[source,python]
----
def calculate(x, y):    1
    result = x + y      2
    return result       3
----
<1> Funktionsdefinition mit zwei Parametern
<2> Berechnung des Ergebnisses
<3> Rückgabe des Werts

Das Ergebnis:

def calculate(x, y):    1
    result = x + y      2
    return result       3
1 Funktionsdefinition mit zwei Parametern
2 Berechnung des Ergebnisses
3 Rückgabe des Werts

Die Callout-Marker <1>, <2>, <3> im Code verweisen auf die Erläuterungen darunter. Mit :icons: font im Dokumentkopf werden die Nummern als kleine Kreise dargestellt.

Für Code-Blöcke ohne Syntax-Highlighting verwenden Sie einen einfachen Listing-Block – nur mit ---- ohne [source,sprache].