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

Hierüber prüfe ich die Codeblock-Optionen in Markdown — wie man die Programmiersprache angibt, Diff-Formatierungen und Dateinamen für Codeblöcke festlegt.

Dieser Leitfaden ist Teil unserer Dokumentationswerkzeuge 2026: Markdown, LaTeX, PDF & Druck-Workflows-Rubrik.

Übersicht zu Markdown-Codeblöcken

Markdown-Codeblöcke zeigen Code oder vorformatierten Text innerhalb von Markdown-Dokumenten an, wobei die Formatierung erhalten bleibt und optional Syntax-Hervorhebungen ermöglicht werden. Es gibt zwei Haupttypen der Code-Formatierung in Markdown: Inline-Code und Codeblöcke.

Typen von Markdown-Codeblöcken

Wichtige Unterschiede

• Inline-Code verwendet einzelne Backticks (`) und ist für kurzen Code innerhalb eines Satzes gedacht.
• Eingeklarte Codeblöcke verwenden vier Leerstellen oder ein Tab am Anfang jeder Zeile. Sie unterstützen keine Syntax-Hervorhebung und sind in modernem Markdown unüblich.
• Umzäunte Codeblöcke (Fenced Code Blocks) 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 die Programmiersprache direkt nach den öffnenden Backticks angeben können, um Syntax-Hervorhebung zu aktivieren.
  • Sie die Formatierung erhalten und mehrzeiligen Code unterstützen.

Beispiel eines umzäunten Codeblocks mit Syntax-Hervorhebung:

Wenn wir den folgenden Markdown-formatierten Text haben:

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

Sieht das gerenderte Ergebnis so aus:

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

Best Practices für Markdown-Codeblöcke

• Verwenden Sie umzäunte Codeblöcke (dreifache Backticks) für mehrzeiligen Code, um Klarheit und Kompatibilität über Plattformen hinweg zu gewährleisten.
• Geben Sie die Sprache nach den öffnenden Backticks an, um Syntax-Hervorhebung zu aktivieren (z. B. ```python).
• Verwenden Sie Inline-Code für kurze Snippets oder Befehle innerhalb des Textes.
• Vermeiden Sie eingeklarte Codeblöcke, es sei denn, sie sind aus Kompatibilitätsgründen mit älteren Systemen erforderlich, da sie keine Syntax-Hervorhebung unterstützen und weniger gut lesbar sein können.
• Lassen Sie eine Leerzeile vor und nach umzäunten Codeblöcken, um die Lesbarkeit im rohen Markdown zu verbessern.

Spezielle Funktionen

• Einige Plattformen unterstützen zusätzliche Sprachbezeichner wie diff zur Anzeige von Codeänderungen, was hinzugefügte oder entfernte Zeilen in Code-Reviews hervorhebt.
• Um Backticks innerhalb eines Codeblocks anzuzeigen, wrappen Sie den Block in eine höhere Anzahl von Backticks (z. B. vier Backticks, um drei Backticks innen anzuzeigen).

Kurzübersicht

Verwenden Sie umzäunte Codeblöcke mit einem Sprachbezeichner für die beste Lesbarkeit und Syntax-Hervorhebung. Reservieren Sie Inline-Code für kurze Snippets und vermeiden Sie eingeklarte Blöcke, es sei denn, sie sind zur Kompatibilität notwendig.

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

Diff-Syntax-Hervorhebung

Diff-Syntax-Hervorhebung ermöglicht es Ihnen, Codeänderungen klar darzustellen — nützlich in Dokumentation, Code-Reviews und technischen Blogs.

• Verwenden Sie umzäunte Codeblöcke mit dreifachen Backticks (```), um Ihren Block zu beginnen und zu enden.
• Geben Sie diff als Sprachbezeichner direkt nach den öffnenden Backticks an.

Beispiel:

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

• Zeilen, die mit - beginnen, werden als Löschungen hervorgehoben (meistens rot).
• Zeilen, die mit + beginnen, werden als Hinzufügungen hervorgehoben (meistens grün).
• Zeilen ohne Präfix werden nicht speziell hervorgehoben.

Best Practices:

• Lassen Sie eine Leerzeile vor und nach Ihrem Codeblock für bessere Lesbarkeit im rohen Markdown.
• Beachten Sie, dass Diff-Hervorhebung nur ganze Zeilen basierend auf dem führenden Zeichen einfärbt; sie hebt keine Inline-Änderungen innerhalb einer Zeile hervor.

Tipp: Diff-Hervorhebung wird auf GitHub, GitLab und den meisten Markdown-Renderern weitgehend unterstützt, was sie zu einer zuverlässigen Wahl für die Kommunikation von Codeänderungen macht.

Unterstützte Sprachen für Syntax-Hervorhebung

Die genaue Menge der unterstützten Sprachen hängt vom Renderer oder der Plattform ab, die Sie verwenden. Markdown übergibt den Sprachbezeichner an die Rendering-Engine, die die entsprechende Syntax-Hervorhebung anwendet. Dies ist wichtig bei der Konvertierung von HTML nach Markdown mit Python, da <code>-Tags mit Sprach-Klassenattributen (z. B. class="language-python") direkt auf diese Bezeichner im umzäunten Block abgebildet werden.

Häufig unterstützte Sprachen auf großen 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
• Spezial: diff, mermaid, geojson, topojson, stl (für Diagramme und Datenvisualisierungen auf GitHub) — der Bezeichner mermaid ermöglicht insbesondere die vollständige Diagramm-Rendering auf unterstützten Plattformen; siehe das Mermaid-Diagramme Quickstart und Cheat Sheet für eine vollständige Syntaxreferenz und Hugo-Setup-Anleitung
• Andere: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme und viele mehr

Wie man eine Sprache angibt:

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

Sprachbezeichner, die in den meisten Renderern unterstützt werden:

Hinweis: Die meisten Renderer sind bei Sprachnamen nicht case-sensitiv. Wenn Sie einen nicht unterstützten Bezeichner verwenden, wird der Codeblock als Klartext gerendert.

Finden der vollständigen Liste unterstützter Sprachen:

• GitHub: Verwendet Linguist, unterstützt Hunderte von Sprachen.
• VS Code & viele Web-Renderer: Verwenden highlight.js oder Pygments—sehen Sie deren Dokumentation für erschöpfende Listen.
• Bitbucket: Verweist auf CodeMirror modes und Pygments-Lexer.

Festlegen eines Dateinamens in einem Markdown-Codeblock

Die Anzeige des Dateinamens neben einem Codeblock hilft Lesern zu identifizieren, zu welcher Datei ein Snippet gehört. Die Unterstützung variiert je nach Plattform.

1. Dateiname im Codeblock-Label (Meta-Syntax)

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

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

Dies zeigt den Dateinamen über oder neben dem Codeblock an. Der Hugo-Renderer dieser Seite unterstützt dies nicht:

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

Hinweis: Dies wird in GitHub-flavored Markdown nicht unterstützt.

2. Manueller Dateiname als Überschrift oder Inline-Code

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

**`app.js`**

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

Oder mit einer Überschrift:

#### `app.js`

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

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

3. Dateiname als Kommentar innerhalb des Codes

Schließen Sie den Dateinamen als Kommentar innerhalb des Codeblocks selbst ein:

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

Dies ist besonders nützlich, wenn Sie möchten, dass der Dateiname sichtbar bleibt, 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 beim Teilen über Plattformen hinweg.

Escaping von Backticks innerhalb von Codeblöcken

Um Backtick-Zäune innerhalb eines Codeblocks anzuzeigen — zum Beispiel beim Schreiben von Dokumentation über Markdown selbst — verschachteln Sie den Block in einer höheren Anzahl von Backticks:

````markdown
```python
# Dieser dreifache-Backtick-Zaun ist innerhalb eines vierfachen-Backtick-Zauns
print("hello")
```
````

Die Verwendung von vier Backticks als äußerer Zaun ermöglicht es Ihnen, Beispiele mit dreifachen Backticks innen anzuzeigen, was für Markdown-Tutorials und Cheat Sheets praktisch ist.

Hugo-spezifisch: Die Highlight-Shortcode

Wenn Sie Hugo verwenden, bietet die eingebaute highlight-Shortcode mehr Kontrolle als einfache umzäunte Blöcke, einschließlich Zeilennummern und hervorgehobener 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 bei 10 beginnen

Dies ist besonders nützlich in Tutorials oder Dokumentation, wo Sie auf bestimmte Zeilen aufmerksam machen möchten. Sehen Sie das Markdown Cheat Sheet für weitere Formatierungsfeatures, und das Hugo Cheat Sheet für eine breitere Referenz zu Hugo-Befehlen und Templates.

Nützliche Links

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