Markdown-Codeblöcke – Cheatsheet und Beispiele zur Verwendung

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 & Druckworkflows-Hubs.

Markdown-Codeblöcke

Markdown-Codeblöcke sind eine Möglichkeit, Code oder vorformatierten Text innerhalb von Markdown-Dokumenten anzuzeigen, wobei die Formatierung bewahrt bleibt und optional eine Syntaxhervorhebung 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 Syntaxhervorhebung und sind in modernem Markdown weniger verbreitet.
• Gefüllte Codeblöcke verwenden dreifache Backticks (```) oder Tildes (~~~) 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 unmittelbar nach den öffnenden Backticks für die Syntaxhervorhebung festlegen können.
  • Sie die Formatierung bewahren und mehrzeiligen Code unterstützen.

Beispiel eines gefüllten Codeblocks mit Syntaxhervorhebung:

Wenn wir den folgenden markdown-formatierten Text haben:

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

Dann sieht der gerenderte Text so aus:

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

Best Practices für die Verwendung von Markdown-Codeblöcken

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

Besondere Funktionen

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

OutTake

Verwenden Sie gefüllte Codeblöcke mit einer Sprachidentifikation für die beste Lesbarkeit und Syntaxhervorhebung. 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.

Diff-Syntaxhervorhebung

Um Diff-Syntaxhervorhebung in Markdown-Codeblöcken effektiv zu verwenden, folgen Sie diesen Schritten:

• Verwenden Sie gefüllte Codeblöcke mit dreifachen Backticks (```) zum Starten und Beenden Ihres Blocks.
• Legen Sie diff als Sprachidentifikator unmittelbar nach den öffnenden Backticks fest. Dies ermöglicht die Syntaxhervorhebung für Unterschiede, ähnlich wie in Git-Commit-Nachrichten oder Pull-Requests.

Beispiel:

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

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

Best Practices:

• Verwenden Sie dieses Format, um Codeänderungen, Korrekturen oder Vorschläge in Dokumentationen, Code-Reviews oder technischen Blogs klar zu kommunizieren.
• Platzieren Sie eine leere Zeile vor und nach Ihrem Codeblock für bessere Lesbarkeit im Roh-Text von Markdown.
• Beachten Sie, dass Diff-Hervorhebung nur ganze Zeilen basierend auf dem führenden Zeichen färbt; sie hervorhebt keine inlinen Änderungen innerhalb einer Zeile.

Tipp:
Diese Methode wird weit verbreitet auf Plattformen wie GitHub, GitLab und vielen Markdown-Renderer unterstützt, wodurch sie eine zuverlässige Wahl für die visuelle Kommunikation von Codeänderungen ist.

Unterstützte Sprachen

Markdown-Codeblöcke unterstützen eine Vielzahl von Sprachen für die Syntaxhervorhebung, aber die genaue Liste der unterstützten Sprachen hängt von dem Renderer oder der Plattform ab, die Sie verwenden. Markdown selbst definiert nicht, welche Sprachen unterstützt werden; es übergibt einfach den Sprachidentifikator an den Rendering-Engine, die dann die passende Syntaxhervorhebung anwendet. Markdown-Codefence selbst definieren keine festgelegte Liste offiziell unterstützter Programmiersprachen. Stattdessen hängt die Liste der unterstützten Sprachen von der Markdown-Renderer oder Plattform ab, die Sie verwenden (z. B. GitHub, GitLab, VS Code, Typora, Quarto usw.).

Häufig unterstützte Sprachen auf großen Plattformen (wie GitHub, VS Code, Bitbucket, Docusaurus und ReadMe) umfassen:

• Web & Skripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmierung: python (py), java, c, c++, 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)
• Andere: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme und viele mehr

Wie man eine Sprache festlegt: Verwenden Sie den Sprachnamen unmittelbar nach den öffnenden dreifachen Backticks:

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

Die folgenden Sprachen werden von MEISTEN Markdown-Renderern weit verbreitet unterstützt:

Hinweis: Der tatsächliche Identifikator kann variieren (z. B. js vs. javascript). Die meisten Renderer sind bei Sprachnamen case-insensitiv.

Wie man die vollständige Liste der unterstützten Sprachen findet:

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

Wichtige Punkte:

• Die meisten Plattformen unterstützen alle großen Programmier-, Skript- und Markup-Sprachen.
• Einige Plattformen unterstützen auch Diagramm- und Datenformate (wie mermaid, geojson).
• Der Sprachidentifikator ist in der Regel case-insensitiv, sollte aber in Kleinbuchstaben für beste Kompatibilität geschrieben werden.
• Wenn Sie einen nicht unterstützten Sprachidentifikator verwenden, wird der Codeblock als reiner Text gerendert.

Dateiname in einem Markdown-Codeblock festlegen

Um einen Dateinamen in einem Markdown-Codeblock festzulegen, haben Sie mehrere Optionen, aber die Methode hängt von der Plattform und dem Renderer ab:

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

Einige Markdown-Engines (z. B. bestimmte statische Seiten-Generatoren, Dokumentations-Tools und Blog-Plattformen) unterstützen eine Meta-Syntax, 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 (z. B. app.js) über oder neben dem Codeblock an, je nach Renderer. Und dieser Website’ Hugo-Renderer tut das nicht:

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

Hinweis: Dies wird nicht auf allen Plattformen unterstützt (z. B. GitHub-flavored Markdown unterstützt diese Funktion derzeit nicht).

2. Manueller Dateiname-Ü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, indem Sie eine Überschrift oder fett formatierten Inline-Code verwenden:

**`app.js`**

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

Oder:

#### `app.js`

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

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

3. Dateiname als Kommentar im Code

Alternativ können Sie den Dateinamen als Kommentar innerhalb des Codeblocks selbst einfügen:

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

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

Zusammenfassung und Best Practices

Verwenden Sie eine Überschrift oder fett formatierten Inline-Code über dem Codeblock für maximale Kompatibilität, und erwägen Sie, einen Kommentar innerhalb des Codes hinzuzufügen, um Klarheit zu gewährleisten, wenn Sie ihn über verschiedene Plattformen hinweg teilen.

Nützliche Links

• Dokumentations-Tools 2026: Markdown, LaTeX, PDF & Druckworkflows
• Markdown-Cheat Sheet – Die nützlichsten Strukturen und Befehle
• Hugo Cheat Sheet
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks