Markdown-Codeblöcke: Vollständiger Leitfaden mit Syntax, Sprachen und Beispielen

Hier bewerte ich Codeblock-Optionen in Markdown – wie man die Programmiersprache, Diff-Formatierung und den Dateinamen des Codeblocks festlegt.

Dieser Leitfaden ist Teil unseres Dokumentations-Tools 2026: Markdown, LaTeX, PDF & Druckworkflow-Hubs.

Übersicht zu Markdown-Codeblöcken

Markdown-Codeblöcke zeigen Code oder vorformatierten Text in Markdown-Dokumenten an, wobei die Formatierung beibehalten wird und optional Syntax-Highlighting aktiviert werden kann. Es gibt zwei Haupttypen der Codeformatierung in Markdown: Inline-Code und Codeblöcke.

Typen von Markdown-Codeblöcken

Wichtige Unterschiede

• Inline-Code verwendet einzelne Backticks (`) und ist für kurze Codeausschnitte innerhalb eines Satzes geeignet.
• Einrückte Codeblöcke verwenden vier Leerzeichen oder einen Tab am Anfang jeder Zeile. Sie unterstützen keine Syntax-Highlighting und sind in modernem Markdown selten.
• Gefüllte Codeblöcke verwenden dreifache Backticks (```) oder Tilden (~~~) vor und nach dem Code. Dies ist die bevorzugte Methode, insbesondere auf Plattformen wie GitHub, weil:
  • Sie leichter zu lesen und zu schreiben sind.
  • Sie können die Programmiersprache unmittelbar nach den öffnenden Backticks für Syntax-Highlighting festlegen.
  • Sie behalten die Formatierung bei und unterstützen mehrzeiligen Code.

Beispiel eines gefüllten Codeblocks mit Syntax-Highlighting:

Wenn wir den folgenden markdown-formatierten Text haben:

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

Der gerenderte Ausgabe sieht so aus:

def hello():
    print("Hello, world!")

Best Practices für Markdown-Codeblöcke

• Verwenden Sie gefüllte Codeblöcke (dreifache Backticks) für mehrzeiligen Code, um Klarheit und Kompatibilität über Plattformen hinweg zu gewährleisten.
• Legen Sie die Sprache nach den öffnenden Backticks fest, um Syntax-Highlighting zu ermöglichen (z. B. ```python).
• Verwenden Sie Inline-Code für kurze Ausschnitte oder Befehle im Text.
• Vermeiden Sie einrückte Codeblöcke, es sei denn, sie sind für die Kompatibilität mit älteren Systemen erforderlich, da sie keine Syntax-Highlighting unterstützen und weniger lesbar sein können.
• Setzen Sie eine leere Zeile vor und nach gefüllten Codeblöcken, um die Lesbarkeit im Roh-Text-Markdown zu verbessern.

Besondere Funktionen

• Einige Plattformen unterstützen zusätzliche Sprachidentifikatoren wie diff, um Codeänderungen anzuzeigen, was hervorhebt, welche Zeilen hinzugefügt oder entfernt wurden, in Code-Reviews.
• Um Backticks innerhalb eines Codeblocks anzuzeigen, umschließen Sie den Block mit einer größeren Anzahl von Backticks (z. B. vier Backticks, um drei Backticks innerhalb anzuzeigen).

Kurzfassung der Referenz

Verwenden Sie gefüllte Codeblöcke mit einer Sprachidentifikation für die beste Lesbarkeit und Syntax-Highlighting. Reservieren Sie Inline-Code für kurze Ausschnitte und vermeiden Sie einrückte Blöcke, es sei denn, sie sind für die Kompatibilität erforderlich.

Codeblöcke passen natürlicherweise zu Tabellen in Markdown um gut strukturierte technische Dokumentation zu erstellen.

Diff-Syntax-Highlighting

Diff-Syntax-Highlighting ermöglicht es, Codeänderungen klar darzustellen – nützlich in Dokumentationen, Code-Reviews und technischen Blogs.

• Verwenden Sie gefüllte Codeblöcke mit dreifachen Backticks (```) um Ihren Block zu starten und zu beenden.
• Legen Sie diff als Sprachidentifikator unmittelbar nach den öffnenden Backticks fest.

Beispiel:

- alte Zeile, die entfernt wird
+ neue Zeile, die hinzugefügt wird
  unveränderte Zeile

• Zeilen, die mit - beginnen, werden als Löschungen hervorgehoben (meist in Rot).
• Zeilen, die mit + beginnen, werden als Hinzufügungen hervorgehoben (meist in Grün).
• Zeilen ohne Präfix werden nicht besonders hervorgehoben.

Best Practices:

• Setzen Sie eine leere Zeile vor und nach Ihrem Codeblock für bessere Lesbarkeit im Roh-Text-Markdown.
• Beachten Sie, dass Diff-Highlighting nur ganze Zeilen basierend auf dem führenden Zeichen färbt; es markiert keine inhaltlichen Änderungen innerhalb einer Zeile.

Tipp: Diff-Highlighting wird weit verbreitet auf GitHub, GitLab und den meisten Markdown-Renderern unterstützt, wodurch es eine zuverlässige Wahl für die Kommunikation von Codeänderungen darstellt.

Unterstützte Sprachen für Syntax-Highlighting

Die genaue Menge an unterstützten Sprachen hängt von der Renderer- oder Plattform ab, die Sie verwenden. Markdown übergibt den Sprachidentifikator an den Rendering-Engine, die die entsprechende Syntax-Highlighting anwendet. Dies ist wichtig, wenn HTML in Markdown mit Python konvertiert wird, da <code>-Tags mit Sprachklassenattributen (z. B. class="language-python") direkt auf diese Identifikatoren in dem gefüllten Block abgebildet werden.

Gängig unterstützte Sprachen auf den größten Plattformen (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web & Skripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmierung: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Daten & Abfragen: sql, r, matlab
• Markup & Konfiguration: markdown, ini, toml, dockerfile, makefile
• Spezielle: diff, mermaid, geojson, topojson, stl (für Diagramme und Datenvisualisierungen auf GitHub)
• Andere: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme und viele mehr

Wie man eine Sprache festlegt:

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

Sprachidentifikatoren, die von den meisten Renderern unterstützt werden:

Hinweis: Die meisten Renderer sind bei Sprachnamen case-insensitiv. Wenn Sie einen nicht unterstützten Identifikator verwenden, wird der Codeblock als einfacher Text gerendert.

Vollständige Liste der unterstützten Sprachen finden Sie:

• GitHub: Verwendet Linguist, unterstützt hunderte von Sprachen.
• VS Code & viele Web-Renderer: Verwenden highlight.js oder Pygments – siehe deren Dokumentation für umfassende Listen.
• Bitbucket: Verweist auf CodeMirror Modi und Pygments Lexer.

Dateiname in einem Markdown-Codeblock festlegen

Das Anzeigen des Dateinamens neben einem Codeblock hilft Lesern, zu erkennen, zu welcher Datei ein Ausschnitt gehört. Die Unterstützung variiert je nach Plattform.

1. Dateiname im Codeblock-Label (Metasyntax)

Einige Markdown-Engines (bestimmte statische Seiten-Generatoren und Dokumentationsplattformen) unterstützen eine Metasyntax, bei der Sie den Dateinamen nach der Sprache anhängen, getrennt durch ein Doppelpunkt:

```js:app.js
console.log("Hello, world!");
```

Dies zeigt den Dateinamen über oder neben dem Codeblock an. Der Renderer dieses Sites (Hugo) unterstützt dies nicht:

console.log("Hello, world!");

Hinweis: Dies wird nicht unterstützt, wenn GitHub-flavored Markdown verwendet wird.

2. Manueller Dateiname-Überschrift oder Inline-Code

Für universelle Kompatibilität (einschließlich GitHub, Stack Overflow und den meisten Markdown-Renderern), setzen Sie den Dateinamen über dem Codeblock mit fettgedrucktem Inline-Code:

**`app.js`**

```js
console.log("Hello, world!");
```

Oder mit einer Überschrift:

#### `app.js`

```js
console.log("Hello, world!");
```

Dies funktioniert überall und verknüpft visuell den Dateinamen mit dem Codeblock.

3. Dateiname als Kommentar innerhalb des Codes

Fügen Sie den Dateinamen als Kommentar innerhalb des Codeblocks selbst ein:

```js
// app.js
console.log("Hello, world!");
```

Dies ist besonders nützlich, wenn Sie den Dateinamen sichtbar haben möchten, wenn der Code kopiert wird.

Kompatibilitätsübersicht

Verwenden Sie fettgedruckten Inline-Code über dem Codeblock für maximale Kompatibilität, und erwägen Sie einen Kommentar innerhalb des Codes für Klarheit, wenn Sie über Plattformen hinweg teilen.

Backticks in Codeblöcken escapen

Um Backtick-Felder innerhalb eines Codeblocks anzuzeigen – zum Beispiel wenn Sie Dokumentation über Markdown selbst schreiben – verschachteln Sie den Block in einer größeren Anzahl von Backticks:

````markdown
```python
# Dieser dreifach-backtick-Feld ist in einem vier-backtick-Feld
print("hello")
```
````

Durch das Verwenden von vier Backticks als äußeren Feld können Sie Beispiele mit dreifachen Backticks innerhalb darstellen, was für Markdown-Tutorials und Cheatsheets nützlich ist.

Hugo-spezifisch: Der Highlight-Shortcode

Wenn Sie Hugo verwenden, bietet der integrierte highlight-Shortcode mehr Kontrolle als einfache gefüllte Blöcke, einschließlich Zeilennummern und hervorgehobenen Zeilen:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Optionen:

• linenos=true — Zeilennummern anzeigen
• hl_lines=2 4 — Zeilen 2 und 4 hervorheben
• linenostart=10 — Zeilennummerierung ab 10 beginnen

Dies ist besonders nützlich in Tutorials oder Dokumentationen, in denen Sie Aufmerksamkeit auf bestimmte Zeilen lenken möchten. Siehe den Markdown-CheatSheet für weitere Formatierungsoptionen und den Hugo-CheatSheet für eine umfassendere Referenz zu Hugo-Befehlen und -Vorlagen.

Nützliche Links

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks