GFM vs. CommonMark vs. Pandoc Markdown: Syntax im Vergleich

Markdown sieht auf den ersten Blick wie eine einzige Sprache aus, bis dieselbe Datei auf GitHub, Hugo, Obsidian oder Pandoc unterschiedlich gerendert wird. Und das Problem liegt nicht darin, dass Markdown unzuverlässig ist.

Das Problem ist, dass „Markdown" eine Familie verwandter Syntaxen, Parser und Plattformfunktionen beschreibt, anstelle eines einzigen universellen Dokumentformats. CommonMark definiert einen präzisen, portablen Kern, GitHub Flavored Markdown fügt Funktionen hinzu, die für die Softwarezusammenarbeit nützlich sind, und Pandoc Markdown erweitert die Sprache zu einem ernsthaften Format für die Dokumenterstellung.

Die Wahl zwischen ihnen hängt davon ab, wo das Dokument gerendert werden muss. Eine README-Datei, ein Hugo-Blogbeitrag und eine akademische Abhandlung haben jeweils unterschiedliche Anforderungen. Dieser Vergleich ist Teil des breiteren Bildes der Dokumentationstools und deckt die formalen Dialekte, plattformspezifische Erweiterungen und praktische Portabilitätsregeln ab, damit Sie die richtige Syntax für Ihre Zielumgebung auswählen können. Für eine kurze Syntaxreferenz deckt der Markdown-Spickzettel die wesentlichen Formatierungselemente ab.

Markdown ist nicht eine einzige Sprache

Die ursprüngliche Markdown-Syntax war bewusst klein und locker spezifiziert. Das machte sie leicht lesbar und zu implementieren, aber verschiedene Parser begannen, mehrdeutige Eingaben unterschiedlich zu interpretieren.

CommonMark wurde erstellt, um konsistente Parse-Regeln für die grundlegenden Markdown-Strukturen zu definieren. GitHub Flavored Markdown, üblicherweise als GFM bezeichnet, baut auf dieser Grundlage auf und fügt mehrere weitverbreitete Erweiterungen hinzu.

Pandoc Markdown verfolgt einen anderen Ansatz. Anstatt eine kleine, auf das Web ausgerichtete Syntax zu bleiben, fügt es Dokumentfunktionen wie Zitate, Metadaten, Fußnoten, Definitionslisten, Attribute und mathematische Notation hinzu.

Ein vereinfachtes Beziehungsdiagramm sieht wie folgt aus:

Diese Hierarchie ist nützlich, aber sie ist in jeder Implementierung keine exakte Vererbung. Jeder Renderer kann Syntax unabhängig aktivieren, deaktivieren oder hinzufügen.

Die kurze Antwort

Verwenden Sie CommonMark-kompatible Syntax, wenn Portabilität am wichtigsten ist.

Verwenden Sie GFM, wenn Sie README-Dateien, Pull Requests, Issue-Vorlagen und technische Dokumentation schreiben, die primär für GitHub-kompatible Plattformen gedacht ist.

Verwenden Sie Pandoc Markdown, wenn das Quelldokument zu PDF, DOCX, EPUB, LaTeX, Foliensätzen oder einer akademischen Abhandlung mit Zitaten und Metadaten werden muss.

Für einen Hugo-Technikblog verwenden Sie den CommonMark-Kern plus die Goldmark-Erweiterungen, die Ihre Website explizit aktiviert. Nehmen Sie nicht an, dass jede Funktion, die auf GitHub sichtbar ist, funktioniert, nur weil Hugo als GFM-kompatibel beschrieben wird.

Meinungsvolle Einschätzung: Wenn Sie sich nur eine Regel für einen Hugo-Technikblog merken können, behandeln Sie CommonMark plus GFM-stilistische Tabellen und Aufgabenlisten als Standard, und behandeln Sie alles andere — Fußnoten, Mathematik, Callouts, Header-Attribute — als eine explizite, getestete Erweiterung und nicht als einen angenommenen Standard. Dieser eine Gewohnheit verhindert die meisten der unten beschriebenen Portabilitätsfehler.

CommonMark: Der portable Kern

CommonMark ist eine formale Spezifikation für die grundlegende Markdown-Sprache. Ihr Hauptbeitrag ist keine große Sammlung von Funktionen, sondern konsistentes Parsen.

Es definiert, wie Parser interpretieren sollten:

• Absätze
• ATX- und Setext-Überschriften
• Blockzitate
• Aufzählungs- und Unnummerierte Listen
• Abgetrennte und eingerückte Codeblöcke
• Betonung und starke Betonung
• Links und Bilder
• Referenzstiltische Links
• Inline-Code
• Thematische Trennlinien
• Roh-HTML-Blöcke
• Harte und weiche Zeilenumbrüche

Ein CommonMark-Dokument kann sich auf der Präsentationsebene dennoch unterschiedlich verhalten. CSS, Syntax-Highlighting, Header-Anker, HTML-Sanitisierung und Linkrichtlinien liegen außerhalb der Kern-Parseteile.

CommonMark sollte daher als eine zuverlässige strukturelle Basis betrachtet werden, nicht als eine Zusage, dass jeder Renderer eine identische Seite erzeugt.

Ein portables CommonMark-Beispiel

# Service-Bereitstellung

Der Dienst stellt eine kleine HTTP-API bereit.

## Anforderungen

- Linux
- Docker
- 8 GB Arbeitsspeicher

## Dienst starten

```bash
docker compose up -d
```

Siehe den [Konfigurationsguide](configuration.md) für Details.

Diese Art von Dokument funktioniert in fast jeder modernen Markdown-Umgebung. Es verwendet Überschriften, Absätze, Listen, abgetrennten Code und gewöhnliche Links, ohne auf dialekt-spezifische Erweiterungen angewiesen zu sein.

GitHub Flavored Markdown: CommonMark für Softwareprojekte

GitHub Flavored Markdown ist ein formaler Dialekt, der auf CommonMark basiert. Er bewahrt das CommonMark-Parse-Modell und fügt Funktionen hinzu, die in der Repository-Dokumentation und -Zusammenarbeit häufig benötigt werden.

Die formale GFM-Spezifikation fügt hinzu:

• Pipe-Tabellen
• Aufgabenlistenelemente
• Durchstreichung
• Erweiterte Autolinks
• Einschränkungen um einige Roh-HTML-Tags

Diese Erweiterungen sind mittlerweile so verbreitet, dass viele Benutzer glauben, sie seien Teil des Standard-Markdown. Sie sind kein Teil des CommonMark-Kerns.

GFM-Tabellen

| Backend | Bester Anwendungsfall |
|---|---|
| Ollama | Lokale Experimente |
| vLLM | Gemeinsame Inferenz |
| SGLang | Strukturierte Workloads |

Ein strikter CommonMark-Parser ist berechtigt, dies als gewöhnlichen Absatztext zu behandeln. Ein GFM-kompatibler Parser erkennt es als Tabelle. Für einen tieferen Einblick in die Tabellensyntax und Ausrichtungsoptionen, siehe Tabellen in Markdown.

GFM-Aufgabenlisten

- [x] Docker installieren
- [x] Modell herunterladen
- [ ] Überwachung hinzufügen

Die Syntax für Aufgabenlisten ist in Issues, Pull Requests und Projekt-Dokumentation nützlich. Außerhalb eines unterstützenden Renderers kann sie als eine gewöhnliche Liste mit buchstäblichen eckigen Klammern erscheinen.

GFM-Durchstreichung

Verwenden Sie den ~~alten Endpunkt~~ neuen Endpunkt.

Durchstreichung wird weitgehend unterstützt, ist aber immer noch eine Erweiterung und keine portable CommonMark-Syntax.

GFM-Autolinks

GFM erkennt mehr URL-ähnlichen und E-Mail-ähnlichen Text, ohne dass spitze Klammern oder explizite Link-Syntax erforderlich sind.

Besuche https://example.com/docs für Details.

In striktem CommonMark verwenden explizite Autolinks spitze Klammern:

<https://example.com/docs>

Die explizite Form ist sicherer, wenn ein Dokument durch unbekannte Markdown-Verarbeiter reisen muss.

GitHub.com unterstützt mehr als formales GFM

Eine häufige Verwirrungsquelle ist die Annahme, dass jede auf GitHub sichtbare Markdown-Funktion zur GFM-Spezifikation gehört.

Das ist es nicht.

GitHub.com fügt plattformeigene Verarbeitungs- und Funktionen um den GFM-Parser hinzu. Abhängig vom Kontext kann GitHub unterstützen:

• Mathematische Ausdrücke
• Mermaid-Diagramme
• Warnungen (Alerts)
• Issue- und Pull Request-Referenzen
• Erwähnungen von Benutzern und Teams
• Commit-Referenzen
• Emoji-Shortcodes
• Aufklappbare HTML-Abschnitte
• Farbvorschauen
• Repository-relative Links
• Automatische Header-Anker

Einige dieser Funktionen sind Syntax-Erweiterungen. Andere sind Post-Verhaltungs-Verarbeitung oder Integrationen mit GitHub-Daten.

Diese Unterscheidung ist wichtig, da ein anderer Renderer GFM-Kompatibilität behaupten kann, ohne GitHub-Mathematik-Renderer, Mermaid-Integration, Issue-Referenzen oder Alert-Stilierung zu implementieren.

GitHub Mermaid-Diagramme

GitHub rendert einen abgetrennten Codeblock, der als mermaid markiert ist, als Diagramm:

```mermaid
flowchart LR
    A[Markdown] --> B[Gerendertes Diagramm]
```

Ein generischer GFM-Renderer kann denselben Block als hervorhebenen Quellcode anzeigen. Der Markdown-Text bleibt gültig, aber das erweiterte Rendering ist plattformspezifisch. Für eine praktische Einführung in Mermaid-Syntax, siehe Mermaid-Diagramme Quickstart.

GitHub Mathematische Ausdrücke

GitHub unterstützt Inline- und Block-Mathematische-Ausdrücke, die Dollar-Trennzeichen und zusätzliche Escape-Formen verwenden.

Die Cache-Größe beträgt ungefähr $2nlhd$ Bytes.

$$
C = 2nlhd
$$

Mathematik ist kein Teil des formalen GFM. Das Verschieben dieses Inhalts in einen anderen Renderer erfordert eine kompatible Mathematik-Erweiterung wie KaTeX, MathJax oder Pandoc-Mathematik-Unterstützung.

GitHub-Warnungen (Alerts)

GitHub unterstützt Blockzitate im Alert-Stil wie z. B.:

> [!WARNING]
> Das Ändern dieser Einstellung leert den Cache.

Auf GitHub kann dies als gestylte Warnung erscheinen. Auf einem reinen CommonMark-Renderer erscheint es normalerweise als ein gewöhnliches Blockzitat, das [!WARNING] enthält.

Dieser Fallback ist lesbar, was GitHub-Warnungen weniger gefährlich macht als Erweiterungen, die völlig verschwinden. Sie sind immer noch keine portablen Präsentationselemente.

Pandoc Markdown: Markdown als Dokumentsprache

Pandoc Markdown ist für die Dokumentumwandlung statt für eine bestimmte Website konzipiert. Es verwendet Markdown als Quelldialekt, um HTML, PDF, DOCX, EPUB, LaTeX, Präsentationen und andere Formate zu erzeugen.

Sein Standard-Markdown-Lesebereich umfasst eine große Erweiterungsreihe. Wichtige Fähigkeiten umfassen:

• YAML-Metadatenblöcke
• Fußnoten
• Zitate
• Mehrere Tabellenformate
• Definitionslisten
• Mathematische Notation
• Header-Identifikatoren und Attribute
• Codeblock-Attribute
• Abgetrennte Divisionen
• Klammer-Spans
• Ober- und Unterindizes
• Durchstreichen
• Zeilenblöcke
• Nummerierte Beispiellisten
• Rohes LaTeX
• Rohes HTML
• Automatische Sektionsnummerierung
• Bibliographie-Verarbeitung

Pandoc Markdown ist viel ausdrucksstärker als CommonMark oder formales GFM. Diese Ausdrucksstärke macht es für das Publishing mächtig, aber weniger sicher als Austauschformat.

Pandoc Fußnoten

Markdown hat mehrere inkompatible Dialekte.[^dialects]

[^dialects]: CommonMark, GFM und Pandoc Markdown sind drei
    wichtige Beispiele.

Die Fußnoten-Syntax wird von vielen modernen Tools unterstützt, ist aber kein Teil von CommonMark oder formalem GFM.

GitHub rendert derzeit Fußnoten in mehreren Inhalt-Kontexten, aber das ist eine GitHub-Plattformfunktion und keine formale GFM-Garantie. Ein Renderer, der nur CommonMark- oder GFM-Kompatibilität behauptet, kann sie möglicherweise nicht unterstützen.

Pandoc Zitate

PagedAttention verbessert die KV-Cache-Speicherverwaltung
[@kwon2023pagedattention].

Mit einer Bibliographie-Datei und einem Zitatstil kann Pandoc dies in ein formatiertes akademisches Zitat und eine Bibliographie auflösen.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

Die Zitat-Syntax bleibt in einem nicht unterstützten Renderer lesbar, aber sie wird ohne Pandoc oder einen anderen kompatiblen Zitat-Verarbeiter nicht zu einer formatierten Referenz. Die Leseseiten-Flexibilität von Pandoc stützt auch Umwandlungsworkflows in die andere Richtung — siehe Word-Dokumente in Markdown konvertieren für ein praktisches Beispiel der Verwendung des erweiterten Pandoc-Dialekts als Zwischenformat.

Pandoc Definitionslisten

CommonMark
: Eine präzise Spezifikation für den Markdown-Kern.

GFM
: Ein CommonMark-basierter Dialekt mit softwareorientierten Erweiterungen.

Pandoc Markdown
: Ein erweitertes Autoring-Format für die Dokumentumwandlung.

Definitionslisten sind in Handbüchern, Glossaren und technischen Büchern nützlich. Sie degradieren normalerweise schlecht in Renderern, die sie nicht unterstützen, da die Zeilen mit Doppelpunkten als ebener Text sichtbar bleiben.

Pandoc Header-Attribute

## Cache-Konfiguration {#cache-config .deployment}

Pandoc interpretiert die geschweifte Klammern als explizite Identifikator- und Klassenliste. Viele andere Markdown-Renderer zeigen den Attribut-Text direkt in der Überschrift an.

Dies ist eines der klarsten Beispiele für nützliche Syntax, die nicht in ein Dokument gehört, das überall gerendert werden soll.

Pandoc Abgetrennte Divisionen

::: warning
Das Ändern dieser Option startet den Server neu.

Pandoc wandelt dies in eine strukturelle Division mit einer Klasse um. Vorlagen, CSS, Filter oder Ausgabe-Verarbeiter können entscheiden, wie diese Struktur erscheinen soll.

Die meisten CommonMark- und GFM-Renderer erkennen den Zaun nicht. Sie zeigen die Doppelpunkte und den Inhalt als gewöhnlichen Text an.

CommonMark vs. GFM vs. Pandoc Markdown

Die folgende Matrix beschreibt die formalen Dialekte, nicht jede Funktion, die von GitHub.com, Hugo, Obsidian, GitLab oder einer anderen Plattform hinzugefügt wurde.

Das Wort „Nein" bedeutet nicht, dass eine Plattform die Funktion nie unterstützen kann. Es bedeutet, dass die Funktion nicht durch die formale Spezifikation dieses Dialekts garantiert wird.

Welche Syntax funktioniert auf GitHub?

Für README-Dateien, Issues, Pull Requests, Diskussionen und Wikis ist GFM die natürliche Basis.

Sie können im Allgemeinen verwenden:

• CommonMark-Syntax
• Tabellen
• Aufgabenlisten
• Durchstreichung
• Erweiterte Autolinks
• Syntax-hervorgehobene Codezäune
• GitHub-spezifische Referenzen
• Von GitHub unterstützte Mathematik
• Von GitHub unterstützte Diagramme
• GitHub-Warnungen
• Fußnoten, wo sie von der Inhaltsoberfläche unterstützt werden

Das Portabilitätsrisiko beginnt, wenn GitHub zusätzliches Rendering über formales GFM hinaus durchführt. Mermaid-Diagramme, mathematische Notation, Issue-Referenzen und Alert-Präsentation können außerhalb von GitHub nicht überleben.

Für Repository-Dateien, die auch anderswo veröffentlicht werden, testen Sie die Quelle im zweiten Renderer, anstatt die GitHub-Vorschau als maßgeblich zu behandeln.

Welche Syntax funktioniert in Hugo?

Hugo verwendet Goldmark als seinen Standard-Markdown-Renderer. Goldmark entspricht CommonMark und bietet Erweiterungen, die mit wichtigen Teilen von GFM kompatibel sind.

In einer typischen Hugo-Konfiguration funktionieren die folgenden gut:

• CommonMark-Struktur
• Abgetrennte Codeblöcke
• Pipe-Tabellen
• Durchstreichung
• Aufgabenlisten
• Automatische Header-IDs
• Syntax-Highlighting
• Fußnoten, wenn die Erweiterung aktiviert ist
• Definitionslisten, wenn aktiviert
• Typografische Ersetzungen, wenn aktiviert

Hugo fügt auch Funktionen außerhalb von Markdown hinzu, durch:

• Frontmatter
• Shortcodes
• Render-Hooks
• Seitenressourcen
• interne Referenzfunktionen
• Template-Verarbeitung
• Website-Konfiguration

Diese Hugo-Funktionen reisen nicht mit der Markdown-Datei. Für ein praktisches Beispiel der Hugo-Bereitstellung, siehe Hugo auf AWS S3 bereitstellen.

Hugo Frontmatter ist kein Markdown-Inhalt

Eine Hugo-Seite beginnt häufig mit YAML-, TOML- oder JSON-Metadaten:

---
title: "Markdown-Kompatibilität"
description: "Vergleichen Sie Markdown-Dialekte und Renderer."
date: 2026-07-31
tags:
  - Markdown
  - Dokumentation
---

Pandoc kann auch YAML-Metadatenblöcke erkennen, aber es interpretiert Felder gemäß seinen eigenen Vorlagen und Verarbeitern. GitHub zeigt normalerweise den Block als eine YAML-ähnliche Sektion an oder behandelt ihn nur in bestimmten Systemen als Repository-Metadaten.

Die gleiche Syntax kann daher in mehr als einem Tool erkannt werden, ohne dass sie die gleiche Semantik hat.

Roh-HTML in Hugo

Goldmark rendert potenziell unsicheres Roh-HTML in einer Standard-Hugo-Konfiguration standardmäßig nicht.

Ein Block wie:

<div class="notice">
  Starten Sie den Dienst nach dem Ändern dieses Werts neu.
</div>

kann weggelassen werden, es sei denn, Roh-HTML-Rendering ist aktiviert oder der Inhalt wird durch einen Shortcode oder einen Render-Hook implementiert.

Für einen kontrollierten Technikblog kann die Aktivierung von Roh-HTML angemessen sein. Es macht die Quelle dennoch weniger portabel und sollte eine bewusste website-übergreifende Entscheidung sein.

Mermaid in Hugo

Ein abgetrennter mermaid-Block ist immer noch nur ein Codeblock, es sei denn, das Hugo-Theme, der Render-Hook, der Shortcode oder der JavaScript-Pipeline wandelt ihn in ein Diagramm um.

GitHub und Hugo können daher identische Mermaid-Quellen akzeptieren und dabei völlig verschiedene Rendermechanismen verwenden.

Welche Syntax funktioniert in Pandoc?

Pandoc kann mehrere Markdown-Dialekte explizit lesen:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

Dies ist eine der nützlichsten Portabilitätsfunktionen von Pandoc. Der Operator kann Pandoc sagen, welchen Dialekt die Quelle zu verwenden vorgibt, anstatt sich auf eine vage .md-Dateiendung zu verlassen.

Pandoc lässt Sie auch zu, individuelle Erweiterungen zu aktivieren oder zu deaktivieren:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

Oder beginnen Sie von einem engeren Format und fügen Sie eine Funktion hinzu:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

Sie können verfügbare Erweiterungen mit Folgendem überprüfen:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

Dieses Erweiterungsmodell ist mächtig, aber es bedeutet, dass „Pandoc Markdown" nicht immer eine feste Konfiguration ist. Build-Befehle und Standarddateien sind Teil der Dokumentenspezifikation.

Welche Syntax funktioniert in Obsidian?

Obsidian speichert Notizen als Markdown-Dateien, aber sein Autoring-Modell umfasst mehrere anwendungsspezifische Funktionen.

Gängige Beispiele umfassen:

• Wiki-Links
• Eingebettete Notizen
• Eingebettete Dateien
• Callouts
• Block-Referenzen
• Tags
• Eigenschaften
• Hervorhebung
• Kommentare
• Dataview-Abfragen aus Plugins
• Anwendungsspezifische URI-Links

Ein Wiki-Link wie:

[[Markdown-Kompatibilität]]

ist innerhalb eines Obsidian-Baults von Bedeutung. GitHub, CommonMark und ein Standard-Pandoc-Lesebereich zeigen es normalerweise als buchstäblichen geklammerten Text an.

Ein Embed ist noch anwendungsspezifischer:

![[kompatibilitaets-tabelle]]

Der referenzierte Inhalt ist nicht in der Datei selbst vorhanden. Das Exportieren oder Veröffentlichen der Notiz erfordert daher einen Erweiterungsschritt, der das Embed auflöst.

Obsidian ist ein gutes Beispiel dafür, warum die Speicherung in .md-Dateien keine Markdown-Portabilität garantiert. Für einen praktischen Blick auf Obsidian als Werkzeug für das Wissensmanagement, siehe Obsidian für das persönliche Wissensmanagement.

Welche Syntax funktioniert in GitLab?

GitLab Flavored Markdown verwendet CommonMark als seinen Kern und umfasst GFM-Funktionen wie Tabellen und Aufgabenlisten. Es fügt dann GitLab-spezifisches Verhalten hinzu, einschließlich Kreuzreferenzen, mathematischer Notation, Diagrammen und anderer Kollaborationsfunktionen.

Eine README, die in konservativem GFM geschrieben ist, bewegt sich in der Regel ohne großen Schaden zwischen GitHub und GitLab.

Plattform-Integrationen reisen nicht so zuverlässig. Issue-Referenzen, Benutzererwähnungen, Diagramme, Mathematik-Verarbeitung und spezielle Blocksyntax können sich unterschiedlich verhalten, selbst wenn die grundlegende Markdown lesbar bleibt.

Plattform-Unterstützungsmatrix

Diese Matrix beschreibt das übliche Standardverhalten. Themes, Plugins, Erweiterungen und Konfiguration können einzelne Zellen ändern.

„Ja" garantiert immer noch nicht identisches HTML oder visuelle Präsentation. Es bedeutet, dass die Umgebung die allgemeine Funktion erkennt.

Syntax, die normalerweise überall sicher ist

Der sicherste portable Teilmenge umfasst:

• ATX-Überschriften, die # verwenden
• Gewöhnliche Absätze
• Leerzeilen zwischen Blöcken
• - für unnummerierte Listen
• 1. für nummerierte Listen
• Abgetrennte Codeblöcke, die Backticks verwenden
• Inline-Code, der Backticks verwendet
• Betonung, die *text* verwendet
• Starke Betonung, die **text** verwendet
• Gewöhnliche Links
• Gewöhnliche Bilder
• Blockzitate
• Thematische Trennlinien
• Explizite spitze-Klammer-Autolinks

Ein absichtlich konservatives Dokument könnte so aussehen:

# Bereitstellungsleitfaden

Dieser Leitfaden erklärt, wie der Dienst bereitgestellt wird.

## Anforderungen

- Docker
- Linux
- Eine unterstützte GPU

## Konfiguration

Erstellen Sie eine Datei namens `compose.yaml`.

```yaml
services:
  application:
    image: example/application:1.0
```

Für weitere Informationen, siehe die [Konfigurationsreferenz](config.md).

> Sichern Sie vorhandene Daten, bevor Sie upgraden.

Diese Syntax reist gut, weil sie sich nicht auf Tabellen, Fußnoten, Attribute, Callouts oder Plattformverarbeitung stützt.

Syntax, die häufig bricht

Portabilitätsprobleme häufen sich um eine kleine Anzahl von Funktionen.

Pipe-Tabellen

Pipe-Tabellen werden von GFM-orientierten Tools gut unterstützt, aber nicht von striktem CommonMark.

Eine Tabelle kann in unlesbaren Text degradieren, wenn sie durch einen Parser weitergeleitet wird, der sie nicht erkennt. Für hochportable Dokumente, erwägen Sie kurze Listen oder semantisches HTML, das während eines Build-Schritts generiert wird.

Fußnoten

Die Fußnoten-Syntax ist weit verbreitet, bleibt aber eine Erweiterung.

Verschiedene Tools können:

• Nur ein Fußnotenformat unterstützen
• Fußnoten unterschiedlich platzieren
• Unterschiedliche Identifikatoren generieren
• Mehrabsatz-Fußnoten ablehnen
• Die Quelle buchstäblich rendern

Verwenden Sie Fußnoten, wenn der Publishing-Pipeline bekannt ist. Vermeiden Sie, sich auf sie in README-Dateien zu verlassen, die auf willkürlichen Systemen gerendert werden müssen.

Header-IDs und Attribute

Diese Pandoc-Syntax ist nicht portabel:

## Installation {#installation .procedure}

Verwenden Sie eine gewöhnliche Überschrift und lassen Sie den Renderer seinen eigenen Anker generieren, wenn Portabilität wichtig ist.

Vermeiden Sie auch, Links zu auto-generierten Header-IDs hart zu codieren, es sei denn, alle Ziele verwenden die gleichen Slugifizierungsregeln.

Callouts und Alerts

GitHub, Obsidian, GitLab, MkDocs, Docusaurus und Hugo-Themes können alle Callout-ähnliche Blöcke unterstützen, aber sie verwenden oft unterschiedliche Syntax.

Ein portabler Fallback ist ein gewöhnliches Blockzitat:

> Warnung: Sichern Sie die Datenbank, bevor Sie upgraden.

Es ist weniger visuell beeindruckend, aber es erhält die Bedeutung überall.

Wiki-Links

Wiki-Links sind in Wissensmanagement-Tools knapp:

[[KV-Cache]]

Sie sind schlechte Austauschsyntax, weil der Zielpfad, der Dateiname, die Header-Regeln und das Verhaltensverhalten zur Anwendung gehören.

Verwenden Sie Standard-Markdown-Links in Inhalten, die für die Veröffentlichung bestimmt sind:

[KV-Cache](kv-cache.md)

Roh-HTML

Roh-HTML ist die übliche Ausweichmöglichkeit, wenn Markdown ein Layout nicht ausdrücken kann. Es ist auch ein häufiger Portabilitäts- und Sicherheitsfehler.

Ein Renderer kann:

• Das HTML entfernen
• Es escapen
• Ausgewählte Elemente sanitisieren
• Blöcke, aber keine Inline-Elemente zulassen
• Markdown-Parsing innerhalb von HTML verweigern
• Es unverändert nur im vertrauenswürdigen Modus durchlassen

Verwenden Sie Roh-HTML nur, wenn das Veröffentlichungsziel kontrolliert wird.

Mathematische Notation

Dollar-abgegrenzte Mathematik ist beliebt, wird aber nicht universell interpretiert.

Die Quelle:

Die Komplexität ist $O(n^2)$.

kann werden:

• Gerenderte Mathematik
• Gewöhnlicher Text mit Dollarzeichen
• Falsche Betonung
• Eingabe für einen anderen Mathematik-Parser

Wählen Sie eine Mathematik-Pipeline und testen Sie sie in jeder Zielumgebung.

Mermaid und andere Diagrammblöcke

Ein Mermaid-Codezarg ist syntaktisch sicher, da nicht unterstützende Renderer ihn normalerweise als Code anzeigen.

Das semantische Ergebnis ist dennoch unterschiedlich. Leser können auf GitHub ein gerendertes Architekturdiagramm und in einer anderen Umgebung den rohen Mermaid-Code sehen.

Dies ist eine sanfte Degradation, keine echte Kompatibilität.

Die drei Ebenen der Markdown-Kompatibilität

Es hilft, Kompatibilität in drei Ebenen zu trennen.

Ebene 1: Parse-Kompatibilität

Erkennt der Parser die Struktur?

Beispiele umfassen Überschriften, Tabellen, Fußnoten und abgetrennte Divisionen.

Ebene 2: Transformationskompatibilität

Wendet die Plattform zusätzliche Verarbeitung an?

Beispiele umfassen:

• Rendering von Mermaid
• Auflösung von Zitaten
• Erweiterung von Wiki-Links
• Verknüpfung von Issue-Nummern
• Verarbeitung von Shortcodes
• Generierung eines Inhaltsverzeichnisses

Ebene 3: Präsentationskompatibilität

Sieht das Ergebnis angemessen aus und verhält es sich entsprechend?

Beispiele umfassen:

• Tabellenstilierung
• Syntax-Highlighting
• Alert-Farben
• Header-Anker
• Responsive Bilder
• Fußnotenplatzierung
• Mathematik-Schriften

Zwei Plattformen können identische Syntax parsen und dabei wesentlich unterschiedliche Präsentationen erzeugen.

Ein besseres Portabilitätsmodell

Stellen Sie nicht die Frage, ob eine Datei „gültiges Markdown" ist, stellen Sie vielmehr vier engere Fragen:

1. In welchem Dialekt ist die Quelle geschrieben?
2. Welcher Parser liest sie?
3. Welche Erweiterungen sind aktiviert?
4. Welche Plattform-Transformationen laufen danach?

Zum Beispiel:

Dialekt: CommonMark plus GFM-Tabellen
Parser: Goldmark
Erweiterungen: Tabellen, Durchstreichung, Aufgabenlisten, Fußnoten
Plattform: Hugo
Zusätzliche Verarbeitung: Render-Hooks und Mermaid-JavaScript

Diese Beschreibung ist viel nützlicher als das Satz „die Website verwendet Markdown".

Einen Dialekt nach Anwendungsfall wählen

README-Dateien

Verwenden Sie GFM.

README-Dateien profitieren von:

• Tabellen
• Aufgabenlisten
• Abgetrenntem Code
• Autolinks
• Durchstreichung
• GitHub-Referenzen

Vermeiden Sie übermäßige Abhängigkeit von GitHub-Only-Funktionen, wenn das Repository nach GitLab gespiegelt wird, auf einer Paketregisterstelle gerendert oder in generierter Dokumentation enthalten ist.

Hugo-Technikartikel

Verwenden Sie CommonMark-kompatibles Markdown mit einem dokumentierten Goldmark-Erweiterungsset.

Tabellen, Codezäune, Fußnoten und Mermaid können angemessen sein, da Sie den Build-Pipeline kontrollieren. Bevorzugen Sie Hugo-Shortcodes oder Render-Hooks gegenüber dem Einbetten großer Mengen von Roh-HTML.

Halten Sie Hugo-spezifische Syntax isoliert und leicht auffindbar.

Akademische Dokumente

Verwenden Sie Pandoc Markdown.

Zitate, Bibliographie-Verarbeitung, Fußnoten, Metadaten, mathematische Notation, Kreuzreferenzen und die Umwandlung in PDF oder DOCX rechtfertigen die reduzierte Portabilität.

Speichern Sie den Pandoc-Befehl, die Standarddatei, Filter, Bibliographie und Vorlagen neben der Quelle. Die Quelldatei allein beschreibt den Build nicht vollständig.

Bücher und Langformat-Dokumentation

Pandoc Markdown ist normalerweise die stärkste der drei Optionen, wenn mehrere Ausgabeformate wichtig sind.

Definitionslisten, Zitate, Attribute, Metadaten und strukturierte Transformationen werden wichtiger, je größer die Dokumentkomplexität wird.

Für nur für das Web bestimmte Dokumentation, die in einem Git-Repository gehostet wird, kann GFM oder ein CommonMark-basierter Dokumentationsgenerator einfacher bleiben.

Notizen und persönliche Wissensdatenbanken

Verwenden Sie die native Syntax der ausgewählten Notizenanwendung, wenn Anwendungsfunktionen echten Mehrwert bieten.

Obsidian-Wiki-Links, Embeds und Callouts sind innerhalb eines Vaults nützlich. Behandeln Sie Export als einen Kompilierprozess, anstatt anzunehmen, dass die rohen Dateien bereits portablen Veröffentlichungen sind.

Geteilte Dokumentation über unbekannte Systeme hinweg

Verwenden Sie eine konservative CommonMark-Teilmenge.

Vermeiden Sie:

• Wiki-Links
• Plattform-Alerts
• Header-Attribute
• Zitate
• Roh-HTML
• Eigene Container
• Anwendungseingebettungen
• Shortcodes

Portabilität erfordert in der Regel, Komfortfunktionen aufzugeben.

Praktische Regeln für portables Markdown

Beginnen Sie mit CommonMark-Struktur

Verwenden Sie CommonMark für das Dokumentenskelett:

• Überschriften
• Absätze
• Listen
• Links
• Bilder
• Blockzitate
• Codeblöcke

Dies stellt sicher, dass die Hauptbedeutung überlebt, auch wenn optionale Erweiterungen fehlschlagen.

Fügen Sie GFM-Funktionen bewusst hinzu

Tabellen und Aufgabenlisten sind angemessen, wenn alle wichtigen Ziele sie unterstützen.

Nehmen Sie nicht an, dass „die meisten Tools GFM unterstützen", ohne das genaue Ziel zu testen. Einige behaupten GFM-Kompatibilität, während sie nur ausgewählte Erweiterungen aktivieren.

Isolieren Sie Plattform-Erweiterungen

Halten Sie plattformspezifische Syntax in klar identifizierbaren Blöcken.

Zum Beispiel, zentralisieren Sie Hugo-Shortcodes, Pandoc-Zitate oder Obsidian-Embeds, anstatt sie durch jeden Absatz zu streuen.

Isolation macht spätere Konversionen einfacher.

Bevorzugen Sie sanfte Degradation

Ein Mermaid-Block degradert in lesbaren Quellcode. Eine GitHub-Warnung degradert in ein Blockzitat.

Ein Wiki-Embed kann in einen unerklärlichen Dateinamen degradieren, während eine Pandoc-abgetrennte Division Interpunktion um den Inhalt freigeben kann.

Wählen Sie Erweiterungen, deren Fallback verständlich bleibt.

Verlassen Sie sich nicht auf auto-generierte Header-IDs

Header-Anker-Algorithmen unterscheiden sich zwischen GitHub, Hugo, Pandoc und Dokumentationsgeneratoren.

Verwenden Sie für Dokument-zu-Dokument-Links nur von Renderern unterstützte explizite IDs, wenn die Zielpipeline kontrolliert wird. Andernfalls verlinken Sie auf das Dokument und nicht auf ein generiertes Fragment.

Halten Sie Build-Konfiguration mit dem Inhalt zusammen

Pandoc-Erweiterungen, Hugo-Einstellungen, Plugins, Filter und JavaScript-Integrationen bestimmen, wie Markdown sich verhält.

Commit relevante Konfigurationsdateien mit der Quelle:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

Eine .md-Dateiendung allein erfasst die Publishing-Umgebung nicht. Für einen strukturierten Ansatz zur Dokumentation dieser Entscheidungen, siehe Entscheidungsprotokolle für KI-gesteuerte Entwicklung.

Testen Sie Markdown gegen jedes wichtige Ziel

Visuelle Vorschau in einem Editor reicht nicht aus. Der Editor kann einen reicheren Dialekt unterstützen als der Produktions-Renderer.

Für Pandoc, testen Sie explizite Eingabeformate:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

Warnungen und sichtbare Quellinterpunktion enthüllen, welche Funktionen dialekt-spezifisch sind.

Für Hugo, bauen Sie die Produktions-Website:

hugo --gc --minify

Prüfen Sie dann das generierte HTML, anstatt sich nur auf eine Editor-Vorschau zu verlassen.

Für Repositories, sehen Sie sich die committete Datei auf der tatsächlichen Hosting-Plattform an. Lokale Markdown-Erweiterungen in VS Code stimmen möglicherweise nicht mit GitHub oder GitLab überein.

Fehlerbehebung bei häufigen Rendering-Ungereimtheiten

Wenn eine Datei, die auf einer Plattform funktioniert hat, auf einer anderen bricht, fällt das Versagen in der Regel in ein paar wiederholbare Muster. Die folgende Tabelle listet das Symptom auf, wie Sie es tatsächlich sehen würden, die wahrscheinlichste Ursache und einen konkreten Befehl oder eine Überprüfung, um es zu bestätigen und zu beheben.

Dies ist der schnellste erste Durchgang, bevor man einen Markdown-„Bug" annimmt — die meisten dieser Ungereimtheiten sind eine fehlende Erweiterung oder eine plattform-eigene Funktion, keine kaputte Syntax. Für Codezarg-spezifische Probleme wie fehlendes Syntax-Highlighting oder nicht unterstützte Sprachidentifikatoren, siehe den dedizierten Leitfaden zu Markdown-Codeblöcken.

Die portbare Teilmenge linten

Ein Markdown-Linter kann Renderer-Kompatibilität nicht garantieren, aber er kann vermeidbare Mehrdeutigkeit entfernen.

Nützliche Regeln umfassen:

• Verwenden Sie konsistente Überschriftenstile
• Fügen Sie Leerzeilen um Listen und Codeblöcke hinzu
• Verwenden Sie abgetrennten statt eingerückten Code
• Geben Sie Codezarg-Sprachen an
• Vermeiden Sie übersprungene Überschriftenlevel
• Verwenden Sie konsistente Listenzusätze
• Vermeiden Sie mehrdeutige Betonung um Interpunktion
• Halten Sie Zeilenende一致ig
• Validieren Sie Links und Bilder

Für Multi-Target-Publishing, fügen Sie für jeden wichtigen Renderer einen Build-Test hinzu, anstatt sich nur auf Syntax-Linting zu verlassen.

Zwischen Dialekten mit Pandoc konvertieren

Pandoc kann Dokumente von einem Dialekt in einen anderen normalisieren:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

Oder konvertieren Sie GFM in Pandoc Markdown:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

Dies ist nützlich, aber Konversion ist nicht garantiert, jede Funktion zu bewahren.

Mögliche Verluste umfassen:

• Plattformspezifische Referenzen
• Callout-Stilierung
• Komplexe Tabellen
• Eingebettete Anwendungsobjekte
• Eigene Attribute
• Roh-HTML-Verhalten
• Plugin-Syntax
• Diagramm-Rendering
• Exaktes Leerzeichen und Formatierung

Pandoc bewahrt die Dokumentstruktur besser als das originale Quellformatierung. Behandeln Sie Konversion als einen Build-Schritt, nicht als einen reversiblen Text-Formatierer.

Empfohlene Strategie für Hugo-Seiten

Für einen Hugo-Technikblog ist die praktischste Politik:

1. Verwenden Sie CommonMark für Kernprosa und Struktur.
2. Aktivieren Sie eine kleine, dokumentierte Reihe von Goldmark-Erweiterungen.
3. Verwenden Sie GFM-stilistische Tabellen und Aufgabenlisten, wo sie die Lesbarkeit verbessern.
4. Implementieren Sie Mermaid durch einen konsistenten Render-Hook oder Shortcode.
5. Behandeln Sie Mathematik durch eine dokumentierte KaTeX- oder MathJax-Pipeline.
6. Verwenden Sie Hugo-Frontmatter nur am Anfang von Inhaltsdateien.
7. Bevorzugen Sie Render-Hooks und Shortcodes gegenüber Roh-HTML.
8. Halten Sie Quell-Links als Standard-Markdown-Links, wo möglich.
9. Testen Sie migrierte oder extern bezogene Dokumente durch Hugo.
10. Dokumentieren Sie jede Syntax, die nicht korrekt auf GitHub gerendert wird.

Dieser Ansatz akzeptiert, dass Hugo-Inhalt nicht universell portabel ist, während er die Portabilitätsgrenze sichtbar hält.

Der schlechteste Ansatz ist versehentliches Dialekt-Mischen: GitHub-Alerts, Obsidian-Embeds, Pandoc-Attribute und Hugo-Shortcodes, die in dasselbe Dokument ohne definierte Build-Pipeline platziert werden.

Entscheidungstabelle

Fazit

CommonMark, GitHub Flavored Markdown und Pandoc Markdown sind keine konkurrierenden Versionen desselben Produkts. Sie lösen unterschiedliche Probleme.

CommonMark bietet eine zuverlässige Parse-Grundlage. GFM fügt praktische Funktionen für die Softwarezusammenarbeit hinzu, während Pandoc Markdown Markdown in eine reiche Quellensprache für Publishing und Konversion verwandelt.

Die sicherste Regel ist einfach: Schreiben Sie den kleinsten Dialekt, der das reale Ziel erfüllt. Verwenden Sie CommonMark, wenn Inhalte reisen müssen, GFM, wenn GitHub-Stil-Kollaboration das Ziel ist, und Pandoc Markdown, wenn Dokumentstruktur und Ausgabeformate wichtiger sind als universelles Rendering.

Markdown-Portabilität wird nicht durch das Vermeiden jeder Erweiterung erreicht. Sie wird dadurch erreicht, dass man weiß, welche Erweiterungen Teil des Quellvertrags sind und sie in jedem Renderer testet, der wichtig ist.

Referenzen

• CommonMark-Spezifikation
• GitHub Flavored Markdown Spec
• Pandoc Markdown
• Goldmark-Dokumentation
• Hugo Goldmark-Konfiguration
• Mathematische Ausdrücke auf GitHub schreiben