GFM vs. CommonMark vs. Pandoc Markdown: Ein Syntax-Vergleich

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

Das Problem besteht darin, dass „Markdown“ eine Familie verwandter Syntaxen, Parser und Plattformeigenschaften beschreibt, statt ein einzelnes universelles Dokumentformat zu sein. 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 Dokumentationsformat.

Die Wahl zwischen ihnen hängt davon ab, wo das Dokument gerendert werden muss. Eine README-Datei, ein Hugo-Blogbeitrag und eine wissenschaftliche Arbeit haben jeweils unterschiedliche Anforderungen. Dieser Vergleich ist Teil des umfassenderen Bilds der Dokumentationswerkzeuge und deckt die formellen Dialekte, plattformspezifische Erweiterungen und praktische Portabilitätsregeln ab, damit Sie die richtige Syntax für Ihre Zielumgebung auswählen können. Für eine schnelle Syntaxreferenz deckt das Markdown-Cheatsheet die wesentlichen Formatierungselemente ab.

Markdown ist nicht nur eine Sprache

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

CommonMark wurde erstellt, um konsistente Parseregeln für die grundlegenden Markdown-Strukturen zu definieren. GitHub Flavored Markdown, meist als GFM bezeichnet, baut auf dieser Grundlage auf und fügt mehrere weit verbreitete Erweiterungen hinzu.

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

Eine vereinfachte Beziehung sieht wie folgt aus:

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

Die kurze Antwort

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

Verwenden Sie GFM beim Schreiben von README-Dateien, Pull Requests, Issue-Vorlagen und technischer Dokumentation, die primär für GitHub-kompatible Plattformen bestimmt ist.

Verwenden Sie Pandoc Markdown, wenn das Quelldokument zu PDF, DOCX, EPUB, LaTeX, Präsentationen oder einem wissenschaftlichen Papier mit Zitaten und Metadaten werden muss.

Für einen technischen Hugo-Blog verwenden Sie den CommonMark-Kern plus die Goldmark-Erweiterungen, die Ihre Site explizit aktiviert. Gehen Sie nicht davon aus, dass jede Funktion, die auf GitHub sichtbar ist, funktioniert, nur weil Hugo als GFM-kompatibel beschrieben wird.

Meinungsbild: Wenn Sie nur eine Regel für einen technischen Hugo-Blog im Gedächtnis behalten, behandeln Sie CommonMark plus GFM-ähnliche Tabellen und Aufgabenlisten als Standard, und behandeln Sie alles andere – Fußnoten, Mathematik, Callouts, Kopfzeilenattribute – als explizite, getestete Erweiterung und nicht als angenommenen Standard. Diese einzelne Gewohnheit verhindert die meisten der unten beschriebenen Portabilitätsfehler.

CommonMark: Der portable Kern

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

Es definiert, wie Parser folgendes interpretieren sollen:

• Absätze
• ATX- und Setext-Kopfzeilen
• Blockzitate
• Geordnete und ungeordnete Listen
• Eingezäunte und eingedentete Codeblöcke
• Betonung und starke Betonung
• Links und Bilder
• Referenz-Links
• Inline-Code
• Thematische Trennungen
• Raw HTML-Blöcke
• Harte und weiche Zeilenumbrüche

Ein CommonMark-Dokument kann sich auf der Präsentationsebene dennoch unterschiedlich verhalten. CSS, Syntaxhervorhebung, Kopfzeilenanker, HTML-Sanitierung und Link-Richtlinien liegen außerhalb der Kernparsregeln.

CommonMark sollte daher als zuverlässige strukturelle Basis behandelt werden, nicht als Garantie, 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

## Starten Sie den Dienst

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

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

Diese Art von Dokument funktioniert in fast jeder modernen Markdown-Umgebung. Es verwendet Kopfzeilen, Absätze, Listen, eingezäunten Code und gewöhnliche Links, ohne sich auf dialekt-spezifische Erweiterungen zu verlassen.

GitHub Flavored Markdown: CommonMark für Software-Projekte

GitHub Flavored Markdown ist ein formeller Dialekt auf Basis von CommonMark. Er bewahrt das CommonMark-Parsmodell und fügt Funktionen hinzu, die häufig in Repository-Dokumentation und Zusammenarbeit benötigt werden.

Die formelle GFM-Spezifikation fügt hinzu:

• Pipe-Tabellen
• Aufgabenlisten-Elemente
• Durchgestrichener Text
• Erweiterte Autolinks
• Einschränkungen bei einigen Raw-HTML-Tags

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

GFM-Tabellen

| Backend | Beste Verwendung |
|---|---|
| Ollama | Lokale Experimente |
| vLLM | Geteilte Inferenz |
| SGLang | Strukturierte Workloads |

Ein strikter CommonMark-Parser darf dies als gewöhnlichen Absatztext behandeln. Ein GFM-kompatibler Parser erkennt es als Tabelle. Für einen tieferen Blick auf die Tabellen-Syntax und Ausrichtungsoptionen siehe Tabellen in Markdown.

GFM-Aufgabenlisten

- [x] Docker installieren
- [x] Modell herunterladen
- [ ] Monitoring hinzufügen

Die Aufgabenlisten-Syntax ist nützlich in Issues, Pull Requests und Projektdokumentation. Außerhalb eines unterstützenden Renderers kann sie als gewöhnliche Liste mit literalen eckigen Klammern erscheinen.

GFM-Durchstreichen

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

Durchstreichen ist weit verbreitet, aber es ist immer noch eine Erweiterung und keine portable CommonMark-Syntax.

GFM-Autolinks

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

Besuchen Sie 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-Prozessoren reisen muss.

GitHub.com unterstützt mehr als formelles GFM

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

Das ist nicht der Fall.

GitHub.com fügt plattformweite Verarbeitung und Funktionen um den GFM-Parser herum hinzu. Je nach Kontext kann GitHub Folgendes unterstützen:

• Mathematische Ausdrücke
• Mermaid-Diagramme
• Warnhinweise (Alerts)
• Issue- und Pull-Request-Referenzen
• User- und Team-Erwähnungen
• Commit-Referenzen
• Emoji-Shortcodes
• Zusammenklappbare HTML-Abschnitte
• Farbvorschauen
• Repository-relative Links
• Automatische Kopfzeilenanker

Einige dieser Funktionen sind Syntaxerweiterungen. Andere sind Post-Processing-Verhalten oder Integrationen mit GitHub-Daten.

Diese Unterscheidung ist wichtig, weil ein anderer Renderer GFM-Kompatibilität beanspruchen kann, ohne den GitHub-Math-Renderer, Mermaid-Integration, Issue-Referenzen oder Alert-Styling zu implementieren.

GitHub Mermaid-Diagramme

GitHub rendert einen eingezäunten Codeblock, der mit mermaid markiert ist, als Diagramm:

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

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

GitHub mathematische Ausdrücke

GitHub unterstützt Inline- und Block-Mathematik mit Dollar-Delimitern und zusätzlichen Escape-Formen.

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

$$
C = 2nlhd
$$

Mathematik ist nicht Teil des formellen GFM. Das Verschieben dieses Inhalts zu einem anderen Renderer erfordert eine kompatible Math-Erweiterung wie KaTeX, MathJax oder Pandoc-Math-Unterstützung.

GitHub Alerts

GitHub unterstützt alert-ähnliche Blockzitate wie:

> [!WARNING]
> Das Ändern dieser Einstellung löscht den Cache.

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

Dieser Fallback ist lesbar, was GitHub-Alerts weniger gefährlich macht als Erweiterungen, die vollständig verschwinden. Sie sind immer noch keine portablen Präsentationselemente.

Pandoc Markdown: Markdown als Dokumentensprache

Pandoc Markdown ist für die Dokumentkonversion而不是 für eine bestimmte Website ausgelegt. Es verwendet Markdown als Quell-Syntax zur Erzeugung von HTML, PDF, DOCX, EPUB, LaTeX, Präsentationen und anderen Formaten.

Sein Standard-Markdown-Reader enthält einen großen Erweiterungsset. Wichtige Fähigkeiten umfassen:

• YAML-Metadatenblöcke
• Fußnoten
• Zitate
• Mehrere Tabellenformate
• Definitionenlisten
• Mathematische Notation
• Kopfzeilen-IDs und Attribute
• Codeblock-Attribute
• Eingezäunte Divisionen
• Bracketed Spans
• Hoch- und Tiefgestellt
• Durchstreichen
• Line Blocks
• Nummerierte Beispiel-Listen
• Raw LaTeX
• Raw HTML
• Automatische Sektionsnummerierung
• Bibliografie-Verarbeitung

Pandoc Markdown ist viel ausdrucksstärker als CommonMark oder formelles GFM. Diese Ausdrucksstärke macht es für die Veröffentlichung leistungsstark, 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 nicht Teil von CommonMark oder formellem GFM.

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

Pandoc-Zitate

PagedAttention verbessert das KV-Cache-Speicher-Management
[@kwon2023pagedattention].

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

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

Die Zitations-Syntax bleibt in einem nicht unterstützenden Renderer lesbar, wird aber ohne Pandoc oder einen anderen kompatiblen Zitationsprozessor kein formatierter Verweis. Die Flexibilität des Pandoc-Readers auf der Eingabeseite unterstützt auch Konvertierungsworkflows in die andere Richtung – siehe Word-Dokumente in Markdown konvertieren für ein praktisches Beispiel für die Verwendung des erweiterten Pandoc-Dialekts als Zwischenformat.

Pandoc-Definitionenlisten

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

GFM
: Ein CommonMark-basierter Dialekt mit softwareorientierten Erweiterungen.

Pandoc Markdown
: Ein erweitertes Authoring-Format für die Dokumentkonversion.

Definitionenlisten sind nützlich in Handbüchern, Glossaren und technischen Büchern. Sie degradieren normalerweise schlecht in Renderern, die sie nicht unterstützen, da die Kolonien als Klartext sichtbar bleiben.

Pandoc-Kopfzeilenattribute

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

Pandoc interpretiert die geschweiften Klammern als explizite ID und Klassenliste. Viele andere Markdown-Renderer zeigen den Attributtext direkt in der Kopfzeile an.

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

Pandoc eingezäunte Divisionen

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

Pandoc konvertiert dies in eine strukturelle Division mit einer Klasse. Templates, CSS, Filter oder Ausgabe-Schreiber können entscheiden, wie diese Struktur aussehen soll.

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

CommonMark vs GFM vs Pandoc Markdown

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

Das Wort „Nein“ bedeutet nicht, dass eine Plattform die Funktion niemals unterstützen kann. Es bedeutet, dass die Funktion nicht durch die formelle 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
• Durchstreichen
• Erweiterte Autolinks
• Syntax-hervorgehobene Code-Zäune
• GitHub-spezifische Referenzen
• GitHub-Unterstützte Mathematik
• GitHub-Unterstützte Diagramme
• GitHub-Alerts
• Fußnoten, wo sie von der Inhaltsoberfläche unterstützt werden

Das Portabilitätsrisiko beginnt, wenn GitHub zusätzliche Rendering-Schritte jenseits des formellen GFM durchführt. Mermaid-Diagramme, mathematische Notation, Issue-Referenzen und Alert-Präsentation überleben möglicherweise nicht außerhalb von GitHub.

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

Welche Syntax funktioniert in Hugo?

Hugo verwendet Goldmark als seinen standardmäßigen Markdown-Renderer. Goldmark konformiert sich mit CommonMark und bietet Erweiterungen, die mit wichtigen Teilen von GFM kompatibel sind.

In einer typischen Hugo-Konfiguration funktionieren Folgendes gut:

• CommonMark-Struktur
• Eingezäunte Codeblöcke
• Pipe-Tabellen
• Durchstreichen
• Aufgabenlisten
• Automatische Kopfzeilen-IDs
• Syntaxhervorhebung
• Fußnoten, wenn die Erweiterung aktiviert ist
• Definitionenlisten, wenn aktiviert
• Typografische Substitutionen, wenn aktiviert

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

• Front Matter
• Shortcodes
• Render Hooks
• Page Resources
• Interne Referenzfunktionen
• Template-Verarbeitung
• Site-Konfiguration

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

Hugo Front Matter 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, interpretiert Felder jedoch gemäß seinen eigenen Templates und Schreibern. GitHub zeigt den Block normalerweise als YAML-ähnlichen Abschnitt an oder behandelt ihn nur in bestimmten Systemen als Repository-Metadaten.

Dasselbe Syntax kann daher in mehr als einem Tool erkannt werden, ohne dieselbe Semantik zu haben.

Raw HTML in Hugo

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

Ein Block wie:

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

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

Für einen kontrollierten technischen Blog kann das Aktivieren von Raw-HTML vernünftig sein. Es macht die Quelle jedoch weniger portabel und sollte eine bewusste Site-Entscheidung sein.

Mermaid in Hugo

Ein eingezäunter mermaid-Block ist immer noch nur ein Codeblock, es sei denn, das Hugo-Theme, der Render Hook, der Shortcode oder die JavaScript-Pipeline transformiert ihn in ein Diagramm.

GitHub und Hugo können daher identische Mermaid-Quellen akzeptieren, während sie völlig unterschiedliche Render-Mechanismen 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 mitteilen, welchen Dialekt die Quelle verwenden soll, anstatt sich auf eine vage .md-Dateierweiterung zu verlassen.

Pandoc ermöglicht es Ihnen auch, einzelne Erweiterungen zu aktivieren oder zu deaktivieren:

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

Oder starten 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 inspizieren:

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

Dieses Erweiterungsmodell ist leistungsstark, aber es bedeutet, dass „Pandoc Markdown“ nicht immer eine feste Konfiguration ist. Build-Befehle und Standarddateien sind Teil der Spezifikation des Dokuments.

Welche Syntax funktioniert in Obsidian?

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

Häufige Beispiele umfassen:

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

Ein Wiki-Link wie:

[[Markdown-Kompatibilität]]

ist innerhalb eines Obsidian-Vaults sinnvoll. GitHub, CommonMark und ein standardmäßiger Pandoc-Reader zeigen es normalerweise als literalen Text in eckigen Klammern 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 Wissensmanagement-Tool siehe Obsidian für Personal Knowledge Management.

Welche Syntax funktioniert in GitLab?

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

Eine in konservativem GFM geschriebene README bewegt sich normalerweise zwischen GitHub und GitLab ohne große Schäden.

Plattformintegrationen reisen nicht so zuverlässig. Issue-Referenzen, User-Erwähnungen, Diagramme, Mathematik-Handling und spezielle Block-Syntax können sich unterschiedlich verhalten, auch wenn das grundlegende Markdown lesbar bleibt.

Plattform-Unterstützungsmatrix

Diese Matrix beschreibt das Standardverhalten von Common Defaults. Themes, Plugins, Erweiterungen und Konfigurationen 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 Subset umfasst:

• ATX-Kopfzeilen mit #
• Gewöhnliche Absätze
• Leere Zeilen zwischen Blöcken
• - für ungeordnete Listen
• 1. für geordnete Listen
• Eingezäunte Codeblöcke mit Backticks
• Inline-Code mit Backticks
• Betonung mit *text*
• Starke Betonung mit **text**
• Gewöhnliche Links
• Gewöhnliche Bilder
• Blockzitate
• Thematische Trennungen
• Explizite Autolinks mit spitzen Klammern

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 den [Konfigurationsreferenz](config.md).

> Sichern Sie vorhandene Daten vor dem Upgrade.

Diese Syntax reist gut, weil sie nicht von Tabellen, Fußnoten, Attributen, Callouts oder Plattformverarbeitung abhängt.

Syntax, die häufig bricht

Portabilitätsprobleme sammeln sich tendenziell 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 geht, 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 üblich geworden, bleibt aber eine Erweiterung.

Verschiedene Tools können:

• Nur ein Fußnotenformat unterstützen
• Fußnoten unterschiedlich platzieren
• Unterschiedliche IDs generieren
• Mehrabsatz-Fußnoten ablehnen
• Die Quelle literal rendern

Verwenden Sie Fußnoten, wenn der Veröffentlichungspipeline bekannt ist. Vermeiden Sie die Abhängigkeit davon in README-Dateien, die über beliebige Systeme gerendert werden müssen.

Kopfzeilen-IDs und Attribute

Diese Pandoc-Syntax ist nicht portabel:

## Installation {#installation .procedure}

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

Vermeiden Sie auch das Hard-Coding von Links zu automatisch generierten Kopfzeilen-IDs, es sei denn, jedes Ziel verwendet dieselben Slugifizierungsregeln.

Callouts und Alerts

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

Ein portabler Fallback ist ein gewöhnliches Blockzitat:

> Warnung: Sichern Sie die Datenbank vor dem Upgrade.

Es ist weniger visuell beeindruckend, aber es bewahrt die Bedeutung überall.

Wiki-Links

Wiki-Links sind prägnant innerhalb von Wissensmanagement-Tools:

[[KV Cache]]

Sie sind eine schlechte Austauschsyntax, weil Zielpfad, Dateiname, Kopfzeilenregeln und Auflosungsverhalten zur Anwendung gehören.

Verwenden Sie standardmäßige Markdown-Links in Inhalten, die zur Veröffentlichung bestimmt sind:

[KV Cache](kv-cache.md)

Raw HTML

Raw HTML ist die übliche Notlösung, 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 sanieren
• Blöcke erlauben, aber keine Inline-Elemente
• Markdown-Parsing innerhalb von HTML verweigern
• Es unverändert nur im vertrauenswürdigen Modus passieren

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

Mathematische Notation

Dollar-delimitierte Mathematik ist beliebt, 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 Math-Parser

Wählen Sie einen Math-Pipeline und testen Sie ihn in jeder Zielumgebung.

Mermaid und andere Diagrammblöcke

Ein Mermaid-Code-Zaun ist syntaktisch sicher, weil nicht unterstützte Renderer ihn normalerweise als Code anzeigen.

Das semantische Ergebnis ist immer noch unterschiedlich. Leser können auf GitHub ein gerendertes Architekturdiagramm sehen und Mermaid-Quellen in einer anderen Umgebung.

Dies ist eine elegante Degradation, keine wahre Kompatibilität.

Die drei Schichten der Markdown-Kompatibilität

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

Schicht 1: Parsing-Kompatibilität

Erkennt der Parser die Struktur?

Beispiele umfassen Kopfzeilen, Tabellen, Fußnoten und eingezäunte Divisionen.

Schicht 2: Transformations-Kompatibilität

Wendet die Plattform zusätzliche Verarbeitung an?

Beispiele umfassen:

• Mermaid rendern
• Zitate auflösen
• Wiki-Links erweitern
• Issue-Nummern verlinken
• Shortcodes verarbeiten
• Inhaltsverzeichnis generieren

Schicht 3: Präsentations-Kompatibilität

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

Beispiele umfassen:

• Tabellen-Styling
• Syntaxhervorhebung
• Alert-Farben
• Kopfzeilenanker
• Responsive Bilder
• Fußnotenplatzierung
• Math-Schriftarten

Zwei Plattformen können identische Syntax parsen, während sie substantially unterschiedliche Präsentation produzieren.

Ein besseres Portabilitätsmodell

Statt zu fragen, ob eine Datei „gültiges Markdown“ ist, stellen Sie vier engere Fragen:

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

Zum Beispiel:

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

Diese Beschreibung ist viel nützlicher, als zu sagen „die Site verwendet Markdown“.

Einen Dialekt nach Anwendungsfall wählen

README-Dateien

Verwenden Sie GFM.

README-Dateien profitieren von:

• Tabellen
• Aufgabenlisten
• Eingezäuntem Code
• Autolinks
• Durchstreichen
• GitHub-Referenzen

Vermeiden Sie übermäßige Abhängigkeit von GitHub-Only-Funktionen, wenn das Repository zu GitLab gespiegelt, auf einem Paketregister gerendert oder in generierte Dokumentation aufgenommen wird.

Hugo-Technische Artikel

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

Tabellen, Code-Zäune, Fußnoten und Mermaid können vernünftig sein, weil Sie den Build-Pipeline kontrollieren. Bevorzugen Sie Hugo-Shortcodes oder Render Hooks gegenüber dem Einbetten großer Mengen von Raw-HTML.

Halten Sie Hugo-spezifische Syntax isoliert und leicht zu finden.

Akademische Dokumente

Verwenden Sie Pandoc Markdown.

Zitate, Bibliografie-Verarbeitung, Fußnoten, Metadaten, mathematische Notation, Cross-Referenzen und Konvertierung zu PDF oder DOCX rechtfertigen die reduzierte Portabilität.

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

Bücher und Langform-Dokumentation

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

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

Für web-only-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 Wert bieten.

Obsidian-Wiki-Links, Embeds und Callouts sind innerhalb eines Vaults nützlich. Behandeln Sie Export als Kompilierungsprozess, anstatt anzunehmen, dass die Rohdateien bereits portable Veröffentlichungen sind.

Geteilte Dokumentation über unbekannte Systeme

Verwenden Sie einen konservativen CommonMark-Subset.

Vermeiden Sie:

• Wiki-Links
• Plattform-Alerts
• Kopfzeilenattribute
• Zitate
• Raw HTML
• Benutzerdefinierte Container
• Anwendungsembeds
• Shortcodes

Portabilität erfordert normalerweise das Aufgeben von Komfortfunktionen.

Praktische Regeln für portables Markdown

Beginnen Sie mit CommonMark-Struktur

Verwenden Sie CommonMark für das Dokumentenskelett:

• Kopfzeilen
• 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 vernünftig, wenn alle wichtigen Ziele sie unterstützen.

Gehen Sie nicht davon aus, dass „die meisten Tools GFM unterstützen“, ohne das genaue Ziel zu testen. Einige beanspruchen 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 Konvertierung einfacher.

Bevorzugen Sie elegante Degradation

Ein Mermaid-Block degradiert in lesbaren Quellcode. Ein GitHub-Alert degradiert in ein Blockzitat.

Ein Wiki-Embed kann in einen unerklärlichen Dateinamen degradieren, während eine Pandoc-eingezäunte Division Interpunktion um den Inhalt herum offenlegen kann.

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

Verlassen Sie sich nicht auf automatisch generierte Kopfzeilen-IDs

Kopfzeilen-Anchor-Algorithmen unterscheiden sich zwischen GitHub, Hugo, Pandoc und Dokumentationsgeneratoren.

Verwenden Sie für Cross-Dokument-Links nur Renderer-unterstützte explizite IDs, wenn die Zielpipeline kontrolliert wird. Verlinken Sie andernfalls auf das Dokument, nicht auf einen generierten Fragment.

Behalten Sie Build-Konfiguration mit dem Inhalt

Pandoc-Erweiterungen, Hugo-Einstellungen, Plugins, Filter und JavaScript-Integrationen bestimmen, wie Markdown funktioniert.

Commit relevante Konfigurationsdateien mit der Quelle:

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

Eine .md-Erweiterung allein fängt die Veröffentlichungsumgebung nicht ein. 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 Produktionsrenderer.

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-Site:

hugo --gc --minify

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

Für Repositories sehen Sie die committete Datei auf der tatsächlichen Hosting-Plattform. 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, auf einer anderen bricht, fällt der Fehler normalerweise in eines von einigen wiederholbaren Mustern. Die Tabelle unten listet das Symptom auf, wie Sie es tatsächlich sehen würden, die wahrscheinlichste Ursache und einen konkreten Befehl oder Check, 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-spezifische Funktion, keine gebrochene Syntax. Für code-fence-spezifische Probleme wie fehlende Syntaxhervorhebung oder nicht unterstützte Sprachidentifikatoren siehe den dedizierten Leitfaden über Markdown-Codeblöcke.

Lint den portablen Subset

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

Nützliche Regeln umfassen:

• Verwenden Sie konsistente Kopfzeilenstile
• Fügen Sie leere Zeilen um Listen und Codeblöcke hinzu
• Verwenden Sie eingezäunten statt eingedenteten Code
• Spezifizieren Sie Code-Zaun-Sprachen
• Vermeiden Sie übersprungene Kopfzeilen-Ebenen
• Verwenden Sie konsistente Listen-Marker
• Vermeiden Sie mehrdeutige Betonung um Interpunktion herum
• Halten Sie Zeilenenden konsistent
• Validieren Sie Links und Bilder

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

Konvertieren zwischen Dialekten mit Pandoc

Pandoc kann Dokumente von einem Dialekt zu einem 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 Konvertierung garantiert nicht, dass jede Funktion erhalten bleibt.

Potenzielle Verluste umfassen:

• Plattformspezifische Referenzen
• Callout-Styling
• Komplexe Tabellen
• Eingebettete Anwendungsobjekte
• Benutzerdefinierte Attribute
• Raw-HTML-Verhalten
• Plugin-Syntax
• Diagramm-Rendering
• Exaktes Whitespace und Formatierung

Pandoc bewahrt Dokumentstruktur besser als ursprüngliche Quellformatierung. Behandeln Sie Konvertierung als Build-Schritt, nicht als umkehrbaren Textformatierer.

Empfohlene Strategie für Hugo-Sites

Für einen technischen Hugo-Blog ist die praktischste Politik:

1. Verwenden Sie CommonMark für Kernprosa und Struktur.
2. Aktivieren Sie einen kleinen dokumentierten Satz von Goldmark-Erweiterungen.
3. Verwenden Sie GFM-ähnliche Tabellen und Aufgabenlisten, wo sie die Lesbarkeit verbessern.
4. Implementieren Sie Mermaid durch einen konsistenten Render Hook oder Shortcode.
5. Behandeln Sie Mathematik durch einen dokumentierten KaTeX- oder MathJax-Pipeline.
6. Verwenden Sie Hugo-Front-Matter nur am Anfang von Inhaltsdateien.
7. Bevorzugen Sie Render Hooks und Shortcodes gegenüber Raw-HTML.
8. Halten Sie Quelllinks als standardmäßige Markdown-Links, wo möglich.
9. Testen Sie migrierte oder extern beschaffte Dokumente durch Hugo.
10. Dokumentieren Sie jede Syntax, die auf GitHub nicht korrekt rendert.

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

Der schlechteste Ansatz ist zufälliges Dialekt-Mischen: GitHub-Alerts, Obsidian-Embeds, Pandoc-Attribute und Hugo-Shortcodes in derselben Datei platziert, ohne einen definierten Build-Pipeline.

Entscheidungstabelle

Schlussfolgerung

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

CommonMark bietet eine zuverlässige Parsing-Grundlage. GFM fügt praktische Funktionen für die Softwarezusammenarbeit hinzu, während Pandoc Markdown Markdown in eine reiche Quellsprache für Veröffentlichung und Konvertierung verwandelt.

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

Markdown-Portabilität wird nicht erreicht, indem man jede Erweiterung vermeidet. Sie wird erreicht, indem man weiß, welche Erweiterungen Teil des Quellvertrags sind, und sie in jedem Renderer testet, der wichtig ist.

Referenzen

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