Markdown-Codeblöcke: Der umfassende Leitfaden mit Syntax, Sprachen und Beispielen

Fenced-Codeblöcke enthalten in Markdown mehrzeiligen Quelltext. Das Token nach dem öffnenden Zaun ist ein Sprachtag, und nur der Renderer entscheidet, welchen Code das Tag hervorhebt.

Dieser Leitfaden ist Teil von Dokumentationstools 2026: Markdown, LaTeX, PDF & Druck-Workflows.

GitHub schlägt den Sprachtag mit Linguist und den Schlüsselwörtern in languages.yml nach. Hugo 0.164 übergibt dasselbe Tag an Chroma. Ein Tag, den Chroma nicht kennt, ist trotzdem ein Codeblock und wird als Normaltext gerendert. Überschriften, Tabellen und die anderen Blocktypen befinden sich im Markdown-Spickzettel.

Übersicht über Markdown-Codeblöcke

Markdown bietet drei Arten, Code zu markieren. Inline-Code ist ein Span innerhalb eines Absatzes. Ein eingerückter Block und ein gefenzter Block sind beide mehrzeilig, und nur der Zaun trägt einen Sprachtag.

Ein eingerückter Block kann keine Sprache tragen. CommonMark behandelt eine um vier Leerzeichen eingerückte Zeile als Code und liefert dem Highlighter nichts, damit er abgleichen kann, weshalb der Zaun die Form ist, die verwendet werden sollte, wenn das Beispiel eingefärbt werden soll.

Ein Zaun besteht aus einer Zeile mit mindestens drei Backticks oder drei Tilden, dem Code und dann einer schließenden Zeile desselben Zeichens mit mindestens gleicher Länge. Die schließende Zeile hat keine Info-Zeichenkette. Um einen Backtick-Zaun mit drei Zeichen innerhalb des Beispiels anzuzeigen, öffnet und schließt man mit vier Backticks. Die Codeblock-Dokumentation von GitHub empfiehlt, vor und nach dem Zaun eine Leerzeile einzufügen, damit die Rohdatei leichter zu lesen ist; der Zaun wird jedoch auch ohne diese Leerzeile korrekt geparst.

Wenn die folgende Quelle als Markdown gespeichert ist:

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

rendernt diese Hugo-Site sie wie folgt:

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

Inline-Code verwendet die gleiche Backtick-Regel im kleineren Maßstab. Ein Paar einzelner Backticks reicht für git status aus. Wenn der Span selbst einen Backtick enthält, verwendet man auf beiden Seiten zwei Backticks:

`` `code` ``

Diff-Syntax-Hervorhebung

Ein Zaun mit dem Tag diff zeigt eine Änderung als Text an. Der Chroma-Lexer von Hugo akzeptiert diff und udiff. GitHub hebt diesen Bezeichner aus seiner Sprachliste hervor.

- old line that will be removed
+ new line that will be added
  unchanged line

Zeilen, die mit - beginnen, erhalten den Löschstil, und Zeilen, die mit + beginnen, erhalten den Einfügestil. Eine Zeile ohne Präfix ist in diesem Lexer Normaltext. Die Färbung betrifft die gesamte Zeile. Ein geändertes Wort in der Mitte einer Zeile wird nicht separat markiert.

Sprachbezeichner

Das erste Wort der Info-Zeichenkette ist die Sprache. Die Hugo-Dokumentation behandelt dieses Wort als case-insensitiv. Wenn Chroma keinen Lexer dafür hat, gibt Hugo 0.164 einen einfachen <pre><code class="language-…"> ohne Highlight-Wrapping aus. Eine lokale Renderung von notalang hat genau das getan. guessSyntax ist standardmäßig auf false gesetzt, und die Hugo-Dokumentation besagt, dass nur fünf Lexer die automatische Erkennung implementieren, daher bleibt ein weggelassenes Tag als Normaltext und wird nicht als erratene Sprache interpretiert.

Das aus diesen Zäunen erzeugte HTML verwendet die Klasse language-python und denselben Token. Diese Klasse muss ein Konverter beibehalten, wenn er eine hervorgehobene Seite wieder in Markdown umwandelt, was die Zuordnung in HTML in Markdown mit Python konvertieren abdeckt.

Die folgenden Bezeichner sind die in der Chroma-Tabelle von Hugo für diese Sprachen aufgeführten. Bei einer Hugo 0.164-Renderung wurden cs, yml und markdown ebenfalls eingefärbt, auch dort, wo die veröffentlichte Tabelle csharp, yaml und md ausgibt.

GitHub-Pages-Sites, die die Hervorhebung weiterhin über Jekyll steuern, benötigen den Bezeichner in Kleinbuchstaben. Die eigenen Doku von GitHub stellt diese Anforderung unabhängig von der Renderte auf github.com dar.

GitHub behandelt auch einige Zäune als Diagramme und nicht als eingefärbten Quelltext: mermaid, geojson, topojson und stl. In der Chroma-Tabelle von Hugo wird mermaid nicht aufgeführt. Auf einer Hugo-Site bleibt der Zaun Quelltext, bis ein Render-Hook, ein Shortcode oder ein Skript ihn zeichnet. Das Mermaid-Diagramme-Schnellstart und Spickzettel deckt diese Einrichtung ab.

Angabe eines Dateinamens

Weder in CommonMark noch in den Codeblock-Dokus von GitHub verwandelt die Info-Zeichenkette den Inhalt in einen Dateinamen. Die Highlight-Optionen von Hugo sind geschweifte Klammern wie {linenos=inline}. Sie enthalten kein Dateinamen-Feld.

Doppelpunkt nach der Sprache

Einige Generatoren behandeln js:app.js als Sprache plus Name:

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

GitHub nicht. Hugo 0.164 behält das gesamte Token als Klasse des Code-Elements bei (language-js:app.js) und gibt keinen Dateinamen aus. Welche Dialekte nach dem ersten Wort Bedeutung hinzufügen, ist der Vergleich in GFM vs CommonMark vs Pandoc Markdown.

Name über dem Zaun

Eine Zeile mit fettem Inline-Code über dem Zaun zeigt den Namen auf GitHub, auf dieser Site und in anderen CommonMark-Renderern an:

**`app.js`**

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

Eine Überschrift funktioniert auf dieselbe Weise:

#### `app.js`

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

Name innerhalb des Beispiels

Ein Kommentar in der ersten Zeile reist mit dem Code mit, wenn jemand den Block kopiert:

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

Backticks escapen

Vier Backticks außen zeigen einen Backtick-Zaun mit drei Zeichen an, was das Muster für eine Seite ist, die Markdown dokumentiert:

````markdown
```python
# This triple-backtick fence is inside a four-backtick fence
print("hello")
```
````

Der schließende Zaun muss dasselbe Zeichen wie der öffnende haben und mindestens so lang sein. Ein kürzerer Schließende beendet den Block zu früh und lässt den Rest des Beispiels als gewöhnliche Absätze stehen.

Hugo-Highlight-Optionen

Die config.toml dieser Site hat keinen [markup.highlight]-Block, daher gelten die Standardwerte von Hugo: Gefenzte Blöcke werden hervorgehoben, der Stil ist monokai, Stile werden inline geschrieben (noClasses true), und Zeilennummern sind aus. Hugo 0.164 färbt einen Zaun ein, der nur eine Sprache anfordert, wie das Python-Beispiel oben.

Zeilennummern und hervorgehobene Zeilen sind Klammer-Optionen nach der Sprache. Dieser Zaun fordert inline Nummern an und markiert Zeile 2:

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

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

linenos akzeptiert inline, table, true oder false. hl_lines ist eine Liste von Zeilennummern oder Bereichen. linenostart setzt die erste angezeigte Nummer. Die gleichen Schlüssel sind case-insensitiv. Der highlight-Shortcode nimmt sie als eine zitierte Zeichenkette an, und diese Zeichenkette rendernte auf Hugo 0.164 immer noch Zeilennummern:

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

Um die Farben in ein Stylesheet zu verschieben, setzt man noClasses auf false und generiert das CSS. Hugo 0.164 akzeptiert --mode und --modeSelector für diesen Befehl:

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector begrenzt jede Regel unter einer Top-Level-Klasse wie .dark .chroma. Die Liste der Flags ist hugo gen chromastyles --help.

Wenn der Zaun falsch aussieht

Prüfen Sie das generierte Element, bevor Sie das Beispiel ändern. Auf dieser Hugo-Version ist eine bekannte Sprache ein div.highlight, dessen Code-Element data-lang auf den Bezeichner gesetzt hat. Ein unbekannter Bezeichner ist ein nacktes pre und code mit class="language-…", was notalang erzeugt hat.

Wenn der Name app.js fehlt und die Klasse language-js:app.js ist, wurde die Doppelpunkt-Form verwendet. Verschieben Sie den Namen in die Zeile über dem Zaun.

Wenn die eigenen Zäune eines Tutorials als lockere Absätze erscheinen, ist der äußere Zaun so lang wie der innere. Verlängern Sie den äußeren Zaun.

Wenn ein kurzer Befehl den Backtick in der Mitte eines Satzes verschluckt, benötigt der Span ein langes Backtick-Paar als das enthaltene Zeichen.

Nützliche Links

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/