# Markdown

## Was es ist

Markdown ist eine Art, ein Dokument als gewöhnliche Textdatei zu schreiben. Einige getippte Konventionen sagen einem Konverter, welches HTML er erzeugen soll: Sternchen um ein Wort für Hervorhebung, eine Raute vor einer Überschrift, ein Bindestrich vor jedem Listeneintrag und eckige Klammern mit anschließenden runden Klammern für einen Link. Der Name bezeichnet sowohl die Syntax als auch das Programm, mit dem sie zuerst erschien. Dateien enden gewöhnlich auf `.md` oder `.markdown`. Auch die daraus entstandenen Dialekte, darunter CommonMark und GitHub Flavored Markdown (GFM), werden unter diesem Namen zusammengefasst.

John Gruber entwickelte Markdown 2004 zusammen mit Aaron Swartz und schrieb den ersten Konverter in Perl. Seine letzte Version, Markdown 1.0.1, ist auf den 17. Dezember 2004 datiert. Das erklärte Ziel war vor allem Lesbarkeit: Ein Markdown-Dokument sollte unverändert als Klartext veröffentlichbar sein und nicht aussehen, als sei es mit Tags oder Formatierungsanweisungen ausgezeichnet worden. Der größte einzelne Einfluss auf die Syntax war laut Gruber die Art, wie Menschen bereits Klartext-E-Mails formatierten. Was die Syntax nicht abdeckt, wird mitten im Text als HTML geschrieben, ohne Umschalter oder Trennzeichen. In seiner Einordnung ist Markdown das Schreibformat und HTML das Veröffentlichungsformat.

Ein paar Zeilen zeigen das meiste davon:

```markdown
Der Umzug dauerte **einen Abend** und verlief in drei Schritten:

- Schreibzugriffe stoppen
- die Daten mit `pg_dump` kopieren
- die [Anwendung](https://example.com/app/) auf den neuen Host umstellen
```

Ein Konverter macht daraus einen Absatz mit einem `strong`-Element, eine Liste mit drei Einträgen, einen Code-Span und einen Link. Der Quelltext liest sich weiterhin wie eine getippte Notiz.

## Warum es wichtig ist

Der Quelltext ist das Dokument, und Klartext überlebt jedes Werkzeug darum herum. Eine Markdown-Datei öffnet sich in jedem Editor, lässt sich in der Versionsverwaltung Zeile für Zeile vergleichen und in einem Pull Request übersichtlich prüfen. Kein Anbieter kann das Format einstellen. Eine Textsammlung von einem System in ein anderes zu verschieben bedeutet, Dateien zu kopieren.

Der Preis ist Mehrdeutigkeit. Das CommonMark-Projekt sagt es deutlich: Grubers Beschreibung legt die Syntax nicht eindeutig fest. Sein Skript hatte Fehler und wurde zuletzt im Dezember 2004 aktualisiert. Deshalb gab es 2014 Dutzende Implementierungen, von denen jede die Lücken auf eigene Weise füllte. Sein Beispiel ist ein Dokument, das in einem GitHub-Wiki anders aussieht als nach der Konvertierung mit Pandoc nach DocBook. Weil Markdown keine Eingabe als Syntaxfehler zurückweist, fällt eine Abweichung erst auf, wenn jemand die Ausgabe ansieht. Das Projekt verweist auf Babelmark 3, das dieselbe Eingabe durch mehr als zwanzig Implementierungen schickt, um ihre Übereinstimmung zu prüfen.

CommonMark begann 2014 und antwortet mit einer von John MacFarlane geschriebenen Spezifikation, die jede Regel an Eingabebeispiele und das genau zu erzeugende HTML bindet: 652 Beispiele in Version 0.31.2 vom 28. Januar 2024. GitHub definiert seinen eigenen Dialekt GFM als echte Obermenge von CommonMark. Hinzu kommen Tabellen, Aufgabenlisteneinträge, Durchstreichungen, erweiterte automatische Links und ein Filter, der eine kurze Liste roher HTML-Tags entschärft. Hugos Markdown-Konverter Goldmark entspricht der CommonMark-Spezifikation und ist mit GFM kompatibel.

Markdown hat auch bei der Übertragung einen Namen. Seit März 2016 registriert RFC 7763 `text/markdown` für die ganze Syntaxfamilie, mit einem erforderlichen Parameter `charset` und einem optionalen Parameter `variant`, der den Dialekt der Datei angibt.

## Wie es in der Praxis aussieht

Die von Hand verfassten Seiten dieser Website liegen in Markdown vor und werden mit Go-Templates gestaltet. Die Credits-Seite nennt beide unter den Werkzeugen, mit denen die Seiten entstehen, neben dem statischen Websitegenerator Hugo. Dieselbe Seite nennt markdownlint unter den Lintern, die den Quelltext prüfen, in einer Qualitätsprüfung, die jeden Diagnosebefund als Fehler zählt.

Die Seite darüber, eine Website für KI-Agenten lesbar zu machen, dreht das Format um: Jede Seite hier hat einen Markdown-Zwilling unter derselben Adresse, erreichbar durch Anhängen von `index.md` oder Anfordern von `text/markdown`. Der Build prüft jeden Zwilling auf übrig gebliebenes Markup und verweigert die Veröffentlichung, wenn einer fehlerhaft ist. Der Zwilling dieser Seite lässt sich mit einer einzigen Anfrage abrufen:

```sh
curl -sL https://engineer.company/ai-ready/index.md
```

Rund 50.000 Wörter Softwaredokumentation wurden in Markdown über GitHub, Craft und Confluence hinweg verfasst, vieles davon von Hand. Sie behandelten Architektur, Prozesse und Anleitungen zu immer wieder gestellten Fragen, blieben versionsverwaltet und auffindbar und halfen Neuen, sich schneller einzuarbeiten.

## Wo es schiefgeht

Fettschrift erscheint als Sternchen. Ein Leser sieht je zwei Sternchen neben einem Wort, das fett sein sollte. Jede Prüfung bleibt grün, weil das HTML gültig ist und die Links weiter funktionieren. CommonMark eröffnet Hervorhebung nur mit einer links flankierenden Folge von Sternchen. Folgt auf die Folge ein Satzzeichen, etwa die Klammer eines Links, zählt sie nur, wenn davor ein Leerraum oder Satzzeichen steht. Ein Buchstabe davor lässt die Sternchen wörtlich stehen. Dasselbe gilt für alles, was eine Template-Engine vor dem Parsen von Markdown dort einfügt: Hugo ersetzt einen Shortcode durch einen Platzhalter aus Buchstaben und Ziffern. Das Markdown-Zwillingstemplate dieser Website dokumentiert, dass das Entfernen des Leerzeichens zwischen einem Shortcode und der danebenstehenden Fettschrift die Hervorhebung auf 60 Listenpunkten in drei Sprachen zerstörte. Behalten Sie das Leerzeichen und prüfen Sie die gerenderte Seite statt des Quelltexts. Die Qualitätsprüfung dieser Website untersucht das gebaute HTML auf Markdown, das einen Leser als Satzzeichen erreicht hat.

Dieselbe Datei wird auf zwei Arten gerendert. Eine verschachtelte Liste wird in einem System flach und bleibt in einem anderen verschachtelt. Oder eine Raute am Zeilenanfang erzeugt bei einem Konverter eine Überschrift und bleibt beim nächsten Text. Nichts meldet das, weil Markdown keine Syntaxfehler zu melden hat. Ursache ist ein Dialektunterschied: Zwei Konverter füllen eine der ursprünglichen Lücken verschieden. Benennen Sie den Dialekt eines Projekts, meistens CommonMark oder GFM, verwenden Sie einen Linter, der die Dateien daran misst, und schicken Sie zweifelhafte Eingaben durch mehrere Implementierungen, bevor Sie sich darauf verlassen.

Die Markdown-Kopie einer Seite enthält HTML. Ein Leser der Klartextversion trifft auf rohe `svg`-Elemente oder eine Telefonnummer, die mit einer numerischen Zeichenreferenz statt des Pluszeichens beginnt. Eine Komponente, die für die Webseite HTML rendert, rendert dasselbe HTML in jedes andere Format, wenn sie keine andere Anweisung erhält. Hugo sucht das Template eines Shortcodes je Ausgabeformat und fällt auf das HTML-Template zurück. Die Shortcode-Templates dieser Website dokumentieren beide Fälle: 49 rohe `svg`-Elemente in der Markdown-Kopie der Credits-Seite und die für HTML maskierte Nummer der Kontaktseite. Jeder Shortcode, der Markup schreibt, bekommt jetzt ein eigenes Template für die Markdown-Ausgabe. Die Qualitätsprüfung stellt außerdem sicher, dass die Markdown-Zwillinge weder rohes HTML noch HTML-Entities enthalten; Code wird dabei übersprungen.

Rohes HTML verschwindet von der Seite. Ein im Markdown geschriebener HTML-Block fehlt auf der gebauten Seite, und der Quelltext sieht richtig aus. Grubers Syntax erlaubt HTML überall im Text, doch ein Konverter darf es verweigern: Hugos Einstellung `unsafe` für Goldmark ist standardmäßig aus, sodass mit Markdown vermischtes rohes HTML nicht gerendert wird. GFM maskiert eine kurze Liste von Tags wie `script` und `iframe`, damit sie als Text erscheinen. Verwenden Sie stattdessen die Mittel des Generators, in Hugo einen Shortcode oder Render Hook, oder schalten Sie die Einstellung bewusst ein und akzeptieren Sie, was sie durchlässt.

Der Linter lässt durch, was er ignorieren soll. Eine Markdown-Datei mit defekter Struktur kommt durch die Prüfung, weil markdownlint nichts meldet. Die Regeln, die den Strukturfehler erkannt hätten, waren ohne schriftliche Begründung in der Konfiguration abgeschaltet. Die Entwicklungsregeln dieser Website halten fest, dass markdownlint einmal über eine JSON-Datei mit sechs deaktivierten Regeln und ohne Kommentare konfiguriert war. Beim Überprüfen der sechs Regeln zeigte sich, dass zwei davon echte Defekte verdeckten. Schreiben Sie den Grund neben jede deaktivierte Regel, in einem Format, das Kommentare zulässt, damit die nächste Person widersprechen kann.

## Weiterführende Lektüre
* CommonMark-Spezifikation — die Spezifikation Regel für Regel, jeweils mit Eingabebeispielen und dem zu erzeugenden HTML.
* CommonMark — warum eine Spezifikation nötig war, wie Implementierungen auseinanderliefen und wer sie pflegt.
* Markdown von John Gruber — die ursprüngliche Beschreibung, das Entwurfsziel und das Perl-Skript.
* Markdown: Syntax — Grubers eigene Beschreibung der Syntax einschließlich der Regel für eingebettetes HTML.
* GitHub-Flavored-Markdown-Spezifikation — GitHubs Dialekt als Obermenge von CommonMark mit einzeln gekennzeichneten Erweiterungen.
* RFC 7763: Der Medientyp text/markdown — der Medientyp, sein erforderlicher Parameter `charset` und sein Parameter `variant`.

=> /de/credits/ Die Credits-Seite nennt beide
=> /de/ai-ready/ Die Seite darüber, eine Website für KI-Agenten lesbar zu machen
=> /de/portfolio/wrote-50000-words-of-software-documentation/ Rund 50.000 Wörter Softwaredokumentation
=> https://spec.commonmark.org/ CommonMark-Spezifikation
=> https://commonmark.org/ CommonMark
=> https://daringfireball.net/projects/markdown/ Markdown von John Gruber
=> https://daringfireball.net/projects/markdown/syntax Markdown: Syntax
=> https://github.github.com/gfm/ GitHub-Flavored-Markdown-Spezifikation
=> https://www.rfc-editor.org/rfc/rfc7763 RFC 7763: Der Medientyp text/markdown

=> https://engineer.company/de/glossary/markdown/ Diese Seite im Web
