Markdown formatieren

Was ein Markdown Formatter macht

Markdown ist nachsichtig. Einen Aufzählungspunkt kannst du mit -, * oder + schreiben, eine Hervorhebung mit * oder _ und eine Überschrift mit einer Reihe Gleichheitszeichen oder mit #. Diese Freiheit ist beim Tippen praktisch, aber eine Datei, die mehrere Leute bearbeiten, mischt schnell jeden Stil. Tabellen verrutschen, Leerzeilen fehlen, und Diffs werden unübersichtlich.

Dieser Formatter schreibt den Quelltext in einem einheitlichen Stil neu. Er basiert auf Prettier, dem Formatter, den die meisten JavaScript-Projekte schon für ihre Dokumentation nutzen. Das Ergebnis passt also zu dem, was Prettier in VS Code oder auf der Kommandozeile liefert.

So nutzt du ihn

1. Füge dein Markdown in das linke Feld ein oder klicke auf Datei öffnen, um eine .md-Datei zu laden. Eingefügter Text wird sofort formatiert.
2. Klicke auf Beispiel, wenn du zuerst ein Beispiel sehen willst.
3. Wähl die Einrückung, die Zeilenbreite und unter Text umbrechen, wie Absätze umbrochen werden: Unverändert lassen, Bei Zeilenbreite oder Eine Zeile pro Absatz.
4. Klicke auf Formatieren (oder Strg und Enter), um nach einer Änderung erneut zu formatieren.
5. Nimm das Ergebnis mit Kopieren oder Herunterladen. Leeren leert die Eingabe.

Nach dem ersten Formatieren folgt die Ausgabe deinem Tippen.

Vorher und nachher

Hier ist eine kurze Datei in gemischtem Stil:

Project Notes
=============
* Install the tools
* Run the build
+ Deploy

|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|

Some *emphasis* and __bold__ text.

Der Formatter liefert:

Project Notes
=============

- Install the tools
- Run the build

* Deploy

| Name  | Role   |
| ----- | ------ |
| Ada   | Admin  |
| Linus | Editor |

Some _emphasis_ and **bold** text.

Einiges ist passiert. Nach der Überschrift folgt jetzt eine Leerzeile. Die erste Liste nutzt -. Fett nutzt ** und kursiv _. Die Tabellenspalten sind aufgefüllt, damit sie in reinem Text untereinanderstehen. Beachte, dass „Deploy“ getrennt geblieben ist: Es hatte ein anderes Aufzählungszeichen, Markdown behandelt es also als zweite Liste, und der Formatter erhält diese Bedeutung, indem er ein anderes Zeichen vergibt.

Tabellen mit Umlauten werden ebenfalls sauber ausgerichtet, weil ä, ö und ü als ein Zeichen zählen. Nur bei Emojis oder breiten asiatischen Zeichen kann die Ausrichtung in manchen Editoren etwas verrutschen.

Lange Absätze umbrechen

Mit Text umbrechen auf Bei Zeilenbreite und einer Zeilenbreite von 60 wird dieser Absatz:

Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.

zu:

Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.

Eine Zeile pro Absatz macht das Gegenteil und fügt umbrochene Zeilen wieder zusammen. Unverändert lassen ist die sichere Voreinstellung, wenn du nicht weißt, was dein Team erwartet.

Was er in Ruhe lässt

Der Formatter ändert das Layout, nicht die Bedeutung. Manches fasst er bewusst nicht an:

• Codeblöcke. Code in einem Codeblock bleibt genau so, wie er geschrieben wurde. Ein als js markierter Block mit const a={b:1} wird nicht umformatiert. Dafür nimmst du den JavaScript Formatter.
• Nummerierte Listen. Beginnt jeder Eintrag mit 1., bleibt 1. in jeder Zeile. Hast du 1, 2, 3 nummeriert, bleibt das so.
• Text, der keine gültige Syntax ist. #Title ohne Leerzeichen ist in CommonMark keine Überschrift und bleibt deshalb ein normaler Absatz. Füge das Leerzeichen ein, dann wird eine Überschrift daraus.
• Inline-HTML. HTML-Tags in deinem Markdown bleiben, wie sie sind.

Tipps

• Formatiere vor dem Commit. Einheitliche Dateien bedeuten, dass der Diff in einem Pull Request nur echte Änderungen zeigt.
• Leg für ein ganzes Repository eine Umbruchregel fest. Gemischte umbrochene und nicht umbrochene Dateien erzeugen große Diffs, sobald jemand sie zum ersten Mal formatiert.
• Eine Tabelle von Hand zu bauen ist mühsam. Der Generator Markdown-Tabelle erstellen gibt dir ein Raster zum Tippen und nimmt Daten aus Tabellenprogrammen an.
• Du brauchst Markdown aus einer Webseite oder einer Word-Datei? Nimm den Konverter HTML in Markdown oder Word in Markdown und räum das Ergebnis dann hier auf.

Andere Wege, Markdown zu formatieren

• VS Code: Installiere die Prettier-Erweiterung, öffne eine .md-Datei und führe Dokument formatieren aus. Das Ergebnis passt zu dieser Seite.
• Kommandozeile: npx prettier --write README.md formatiert eine Datei direkt. Füge --prose-wrap always hinzu, um Absätze umzubrechen.
• Linting: markdownlint prüft Stilregeln wie Überschriftenebenen und Zeilenlänge. Es meldet Probleme, während ein Formatter das Layout für dich korrigiert. Viele Projekte nutzen beides.

Grenzen

Der Formatter folgt CommonMark mit GitHub-Erweiterungen wie Tabellen und Aufgabenlisten. Erweiterungen anderer Tools, etwa eigene Container oder Wiki-Links, werden als normaler Text behandelt und womöglich anders umbrochen, als das jeweilige Tool erwartet. Front Matter am Anfang einer Datei (der Block zwischen zwei ----Zeilen) bleibt erhalten. Sehr große Dateien funktionieren, das Formatieren dauert aber länger, weil alles auf deinem Gerät passiert.