Das Markdown, das Sie zurückbekommen, und wie Sie es aufräumen
Zuletzt geprüft
Die Umwandlung liefert Ihnen eine Markdown-Datei, kein fertiges Dokument. Dies ist ein kurzer Feldführer dazu, was herauskommt, welchen Teilen Sie trauen können und welche wenigen Änderungen sich lohnen, bevor die Datei in ein Repository, ein Wiki oder eine Notizsammlung wandert.
7 Minuten Lesezeit
Was die Ausgabe eigentlich ist
Der Konverter gibt GitHub Flavored Markdown aus, den Dialekt von GitHub, GitLab, Obsidian, Notion-Importen und den meisten Static-Site-Generatoren. Es ist CommonMark plus einige Ergänzungen, von denen hier die Pipe-Tabellen zählen.
Diese Wahl ist bewusst. Reines CommonMark hat überhaupt keine Tabellensyntax, ein Konverter mit diesem Ziel würde also entweder Tabellen verwerfen oder rohes HTML ausgeben. GFM-Tabellen lassen sich als Text lesen und werden fast überall verstanden, wo Markdown verstanden wird.
Was die Reise übersteht
| Überschriften | Ja — als #, ##, ### aus der relativen Schriftgröße |
|---|---|
| Absätze | Ja — aus dem senkrechten Abstand |
| Fett und kursiv | Ja — aus Schnitt und Neigung der Schrift selbst |
| Aufzählungen | Ja — aus vorangestellten Aufzählungszeichen |
| Nummerierte Listen | Ja — aus vorangestellten Ziffern |
| Tabellen | Einfache rechteckige, als GFM-Pipe-Tabellen |
| Inline-Code | Ja — aus dicktengleichen Textläufen |
| Links | Ja, wo das PDF eine echte Linkannotation trägt |
| Bilder | Nein — die Ausgabe ist Text und Struktur |
| Fußnoten | Als Fließtext am Seitenende, nicht verknüpft |
| Mathematik | Als die Zeichen, aus denen sie besteht, nicht als LaTeX |
| Farbe und Schriften | Nein — Markdown kann sie nicht ausdrücken |
Die fünf Änderungen, die sich jedes Mal lohnen
Die meisten umgewandelten Dateien brauchen dieselben wenigen Durchgänge. Sie kosten ein paar Minuten und machen den Unterschied zwischen einer Datei, die man durchsuchen kann, und einer, die man lesen kann.
- Bringen Sie die Überschriftenleiter in Ordnung. Größenschwellen erzeugen Ebenen, die lokal richtig und im Ganzen ungleichmäßig sind — ein Dokument kann mit drei H1 und keinem einzigen H2 enden. Überfliegen Sie nur die Überschriften und nummerieren Sie so um, dass die Verschachtelung der wirklichen Gliederung entspricht.
- Fügen Sie zerteilte Absätze wieder zusammen. Ein großzügig gesetztes Dokument bricht Absätze an weichen Zeilenenden. Das liest sich wie ein Stapel kurzer Zeilen; fügen Sie sie zusammen und löschen Sie die überzähligen Leerzeilen.
- Reparieren Sie die Silbentrennung. Blocksatz mit Trennung am rechten Rand hinterlässt über Zeilen geteilte Wörter: „Umwand-“ und dann „lung“. Suchen Sie in der Datei nach einem Bindestrich unmittelbar vor einem Zeilenumbruch.
- Prüfen Sie jede Tabelle. Zählen Sie die Spalten im Markdown gegen das Original und kontrollieren Sie die letzte Zeile — die Schlusszeile ist das häufigste Opfer. Eine Tabelle, die ihre Form verloren hat, ist meist schneller neu getippt als repariert.
- Löschen Sie das Seitenmobiliar. Wiederkehrende Kopf- und Fußzeilen werden erkannt und entfernt, aber ein Dokument, das sie variiert — auf jeder Seite ein anderer Kapiteltitel — kann Reste hinterlassen.
Eine Anmerkung zu Tabellen
Eine GFM-Pipe-Tabelle braucht in jeder Zeile gleich viele Zellen, und die Trennzeile unter dem Kopf legt die Spaltenzahl für die ganze Tabelle fest. Verzählt sich der Konverter in einer Zeile, ist die Tabelle ungültig und erscheint als wörtlicher Text mit senkrechten Strichen.
Das ist ein sichtbares Scheitern, und das ist ein Segen: Sie sehen es sofort, statt es später zu entdecken. Diese Tabelle ist kaputt:
| Region | Q1 | Q2 |
| --- | --- | --- |
| Nord | 120 | 140 |
| Süd | 95 |
| Ost | 88 | 102 |Die Reparatur
Ergänzen Sie die fehlende Zelle, leer, wenn die Quellzelle leer war. Jede Zeile muss so viele Striche haben wie die Trennzeile.
| Region | Q1 | Q2 |
| --- | --- | --- |
| Nord | 120 | 140 |
| Süd | 95 | |
| Ost | 88 | 102 |Maskierung, und warum manchmal Backslashes auftauchen
Markdown gibt Zeichen eine Bedeutung, die in gewöhnlicher Prosa vorkommen. Ein Sternchen bedeutet Hervorhebung, ein Unterstrich bedeutet Hervorhebung, ein Rautezeichen am Zeilenanfang bedeutet eine Überschrift, eine führende Zahl mit Punkt bedeutet einen Listenpunkt.
Wo diese Zeichen in Ihrem Dokument als sie selbst vorkommen — ein Fußnotenzeichen, ein Variablenname mit Unterstrichen, eine Zeile, die tatsächlich mit „1985.“ beginnt —, müssen sie mit einem Backslash maskiert werden, sonst verändern sie stillschweigend die Darstellung. Ein Backslash in der Ausgabe ist meist der Konverter, der sorgfältig arbeitet, kein Fehler.
Wenn ein Backslash stört, ist das Löschen unbedenklich, solange Sie anschließend prüfen, wie die Zeile dargestellt wird.
Wohin die Datei danach geht
Markdown ist reiner Text, und genau das ist der Grund, überhaupt umzuwandeln: Es lässt sich mit grep durchsuchen, mit diff vergleichen und in fünfzig Jahren von allem lesen, was eine Textdatei öffnen kann.
Für ein Repository legen Sie sie in den Baum und lassen das Code-Review seine Arbeit tun. Für eine Notizsammlung prüfen Sie zuerst die Überschriftenleiter, denn die meisten bauen ihre Gliederung daraus. Für eine statische Website ergänzen Sie das Front Matter, das Ihr Generator braucht — kein Konverter kann es erfinden, weil es nicht im PDF steht. Zum Füttern eines Sprachmodells siehe den Leitfaden zur Vorbereitung von PDFs für Retrieval; das ist eine andere Aufgabe mit anderen Prioritäten.