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:

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

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`.

hDiese Seite im Web	URL:https://engineer.company/de/glossary/markdown/	engineer.company	70
