Markdown-Codeblöcke – Cheat-Sheet und Beispiele zur Verwendung

Hier überprüfe ich die Codeblock-Optionen in Markdown.

Markdown-Codeblocks

Markdown-Codeblocks sind eine Möglichkeit, Code oder vorformatierten Text innerhalb von Markdown-Dokumenten anzuzeigen, wobei die Formatierung beibehalten und optional eine Syntax-Hervorhebung ermöglicht wird. Es gibt zwei Haupttypen von Codeformatierungen in Markdown: Inline-Code und Codeblocks.

Typen von Markdown-Codeblocks

Wesentliche Unterschiede

• Inline-Code verwendet einfache Backticks (`) und ist für kurze Code-Snippets innerhalb eines Satzes gedacht.
• Eingezogene Codeblocks verwenden vier Leerzeichen oder einen Tab am Anfang jeder Zeile. Sie unterstützen keine Syntax-Hervorhebung und sind in modernem Markdown weniger verbreitet.
• Eingefasste Codeblocks verwenden dreifache Backticks (```) oder Tilden (~~~) vor und nach dem Code. Dies ist die bevorzugte Methode, insbesondere auf Plattformen wie GitHub, weil:
  • Sie sind einfacher zu lesen und zu schreiben.
  • Sie ermöglichen die Angabe der Programmiersprache unmittelbar nach den öffnenden Backticks für die Syntax-Hervorhebung.
  • Sie erhalten die Formatierung und unterstützen mehrzeiligen Code.

Beispiel eines eingefassten Codeblocks mit Syntax-Hervorhebung:

Wenn wir den folgenden markdown-formatierten Text haben:

```python
def hello():
    print("Hallo, Welt!")
```

Dann würde der gerenderte Text so aussehen:

def hello():
    print("Hallo, Welt!")

Beste Praktiken für die Verwendung von Markdown-Codeblocks

• Verwenden Sie eingefasste Codeblocks (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 für die Syntax-Hervorhebung an (z. B., ``````python).
• Verwenden Sie Inline-Code für kurze Snippets oder Befehle innerhalb des Textes.
• Vermeiden Sie eingezogene Codeblocks, es sei denn, sie sind für die Abwärtskompatibilität erforderlich, da sie keine Syntax-Hervorhebung unterstützen und weniger lesbar sein können.
• Platzieren Sie eine Leerzeile vor und nach den eingefassten Codeblocks, um die Lesbarkeit im Roh-Markdown zu verbessern.

Spezialfunktionen

• Einige Plattformen unterstützen zusätzliche Sprachidentifikatoren wie diff zum Anzeigen von Code-Änderungen, die hinzugefügte oder entfernte Zeilen in Code-Reviews hervorheben können.
• 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).

Zusammenfassung

Verwenden Sie eingefasste Codeblocks mit einem Sprachidentifikator für die beste Lesbarkeit und Syntax-Hervorhebung. Verwenden Sie Inline-Code für kurze Snippets und vermeiden Sie eingezogene Blöcke, es sei denn, sie sind für die Kompatibilität erforderlich.

Diff-Syntax-Hervorhebung

Um die Diff-Syntax-Hervorhebung in Markdown-Codeblocks effektiv zu nutzen, befolgen Sie diese Schritte:

• Verwenden Sie eingefasste Codeblocks mit dreifachen Backticks (```) zum Starten und Beenden Ihres Blocks.
• Geben Sie diff als Sprachidentifikator unmittelbar nach den öffnenden Backticks an. Dies ermöglicht die Syntax-Hervorhebung 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 (meistens rot) hervorgehoben.
• Zeilen, die mit + beginnen, werden als Hinzufügungen (meistens grün) hervorgehoben.
• Zeilen ohne Präfix werden nicht besonders hervorgehoben.

Beste Praktiken:

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

Tipp: Diese Methode wird auf Plattformen wie GitHub, GitLab und vielen Markdown-Rendern weit unterstützt und ist daher eine zuverlässige Wahl, um Code-Änderungen visuell zu teilen.

Unterstützte Sprachen

Markdown-Codeblocks unterstützen eine Vielzahl von Sprachen für die Syntax-Hervorhebung, aber die genaue Liste der unterstützten Sprachen hängt vom Renderer oder der Plattform ab, die Sie verwenden. Markdown selbst definiert nicht, welche Sprachen unterstützt werden; es übergibt einfach den Sprachidentifikator an die Rendering-Engine, die dann die entsprechende Syntax-Hervorhebung anwendet. Markdown-Codefences definieren selbst keine feste Liste offiziell unterstützter Programmiersprachen. Stattdessen hängt die Liste der unterstützten Sprachen vom Markdown-Renderer oder der Plattform ab, die Sie verwenden (wie 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 & Abfrage: 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 angibt: Verwenden Sie den Sprachnamen unmittelbar nach den öffnenden dreifachen Backticks:

```python
def hello():
    print("Hallo, Welt!")
```

Die folgenden Sprachen werden weit über MEISTE Markdown-Renderer unterstützt:

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

Finden der vollständigen Liste der unterstützten Sprachen:

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

Wesentliche Punkte:

• Die meisten Plattformen unterstützen alle wichtigen 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 für die beste Kompatibilität kleingeschrieben werden.
• Wenn Sie einen nicht unterstützten Sprachidentifikator verwenden, wird der Codeblock als reiner Text gerendert.

Angabe des Dateinamens in einem Markdown-Code-Block

Um einen Dateinamen in einem Markdown-Code-Block anzugeben, haben Sie mehrere Optionen, wobei die Methode von der Plattform und dem Renderer abhängt:

1. Dateiname in der Code-Block-Beschriftung (Meta-Syntax)

Einige Markdown-Engines (wie bestimmte statische Site-Generatoren, Dokumentationstools und Blogging-Plattformen) 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 (z. B. app.js) oberhalb oder neben dem Code-Block an, abhängig vom Renderer. Und der Hugo-Renderer dieser Website macht das nicht:

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

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

2. Manuelle Dateinamen-Überschrift oder Inline-Code

Für universelle Kompatibilität (einschließlich GitHub, Stack Overflow und den meisten Markdown-Rendern) platzieren Sie den Dateinamen oberhalb des Code-Blocks, unter Verwendung einer Überschrift oder fettem Inline-Code:

**`app.js`**

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

Oder:

#### `app.js`

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

Dies verbindet den Dateinamen visuell mit dem Code-Block und funktioniert überall.

3. Dateiname als Kommentar im Code

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

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

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

Zusammenfassung und beste Praxis

Verwenden Sie eine Überschrift oder fettem Inline-Code oberhalb des Code-Blocks für maximale Kompatibilität und überlegen Sie, einen Kommentar innerhalb des Codes für Klarheit hinzuzufügen, wenn Sie den Code auf verschiedenen Plattformen teilen.

Nützliche Links

• Markdown Cheatsheet - Die nützlichsten Strukturen und Befehle
• Hugo Cheat Sheet
• Bash Cheat Sheet - Die nützlichsten Bash-Befehle
• LaTeX Cheat Sheet
• Die beliebtesten Themen für Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks