Markdown in PDF umwandeln, ohne das Dokument zu verlieren
Markdown ist für einen scrollenden Bildschirm geschrieben. Ein PDF hat Seiten, und Seiten haben Ränder. Die meisten Konverter ignorieren diesen Unterschied: Sie übergeben die Datei an einen Browser, drücken auf Drucken und schicken zurück, was dabei herauskommt. Deshalb verliert eine Tabelle ihre letzten vier Spalten, landet eine Überschrift am Seitenende und erscheint das Logo oben in einer README als rohe HTML-Zeile, die als Text gedruckt wird. Dieser Konverter richtet das Dokument zuerst für Papier aus und sagt Ihnen anschließend, was dafür nötig war.
Tabellen, die noch aufs Papier passen
Eine Markdown-Tabelle enthält keine Spaltenbreiten. Die Syntax bietet dafür keinen Platz, also hofft ein Konverter, der die Tabelle direkt an den Browser übergibt, dass sie zufällig passt. Hier wird jede Tabelle vor dem Zeichnen vermessen und an das von Ihnen gewählte Papier angepasst. Eine Tabelle mit Dateipfaden und vierzehn Spalten bleibt innerhalb der Ränder, lange Werte werden umgebrochen statt über den Rand hinauszulaufen, und im Ergebnis steht, dass dies nötig war.
Die stillere Hälfte des Problems zeigt sich auf Seite zwei. Eine lange Tabelle lässt ihre Kopfzeile meist auf Seite eins zurück, sodass der Leser ein Gitter aus unbeschrifteten Zahlen erhält. Hier wird die Kopfzeile auf jeder Seite wiederholt, auf der die Tabelle erscheint, und eine Zeile wird nie durch einen Seitenumbruch geteilt.
Code, der den Rand überlebt
Eingeschlossene Codeblöcke behalten ihre Hervorhebung und ihre Sprachmarkierung. Lange Zeilen werden umgebrochen, sodass Sie sehen, dass sie umgebrochen wurden, statt einfach am Seitenrand abgeschnitten zu werden. Ein PDF hat keinen Scrollbalken, daher fehlt bei einer nicht umgebrochenen Zeile die rechte Seite. Eingezogene Blöcke, Fences ohne Sprache und Inline-Code werden alle korrekt übernommen.
Die Bilder in Ihrer README
Ein Logo und eine Reihe von Build-Badges werden fast nie in Markdown geschrieben. Es gibt keine Möglichkeit, ein Bild darin zu zentrieren, daher greifen README-Dateien auf rohes HTML zurück. Ein Konverter, der HTML nicht rendert, maskiert es meist, statt es zu ignorieren – das führt dazu, dass das Dokument mit einer Bildschirmseite voller Bild-Tags als Text beginnt. Hier wird das Markup entfernt und die Bilder sowie die darin enthaltenen Wörter übernommen, sodass der Dokumentenkopf wie gewünscht aussieht.
Bilder werden abgerufen und in die Datei eingebettet, statt nur verlinkt zu werden, sodass das PDF auch offline und noch in einem Jahr funktioniert. Falls ein Bild nicht abgerufen werden kann, wird dies im Ergebnis gezählt und angegeben, statt einfach eine Lücke zu hinterlassen, wo ein Bild sein sollte.
Ihre Überschriften werden zur Navigation
Jedes PDF enthält einen Lesezeichenbaum, der aus Ihren eigenen Überschriften erstellt wird, sodass Sie ein langes Dokument über die Seitenleiste statt durch Scrollen durchgehen können. Fordern Sie ein Inhaltsverzeichnis an, erhalten Sie ein klickbares – und zwar in der von Ihnen gewünschten Überschriften-Tiefe. Eine einzelne Überschrift ganz oben wird als Dokumenttitel gelesen und aus der Liste ausgelassen, wie es sich für einen Buchtitel und nicht für ein Kapitel gehört.
Fußnoten bleiben Fußnoten, mit hochgestelltem Marker und einem Link zurück zur Zeile, die Sie gerade gelesen haben. Aufgabenlisten behalten ihre Kästchen, abgehakt oder nicht. Hinweise, Warnungen und Tipps behalten ihren Farbbalken. Front Matter am Dateianfang wird als Metadaten behandelt und erscheint nicht auf der Seite. Definitionslisten, Durchstreichungen, verschachtelte Zitate und dreifach verschachtelte Listen werden alle korrekt dargestellt.
Es sagt Ihnen, was nicht möglich war
Jede Umwandlung kommt mit einem kurzen Bericht zurück: wie viele Seiten, in welche Richtung der Text läuft, wie viele Tabellen, wie viele Codeblöcke, wie viele Bilder eingebettet wurden und wie viele nicht abgerufen werden konnten. Falls ein Zeichen in einer Schriftart fehlt, wird es aufgelistet. Falls Sie ein Inhaltsverzeichnis angefordert haben, das Dokument aber keine Überschriften enthält, wird dies angegeben, statt Ihnen eine Datei mit einer leeren Seite vorne zu liefern. Ein Konverter, der seine eigenen Fehler verschweigt, ist der Grund, warum Nutzer Konvertern nicht mehr vertrauen.
Schriften, die nicht lateinisch sind
Schriften werden im PDF eingebettet, sodass ein Dokument überall gleich aussieht, auch wenn auf dem Gerät keine dieser Schriften installiert ist. Rechts-nach-links-Text wird abschnittsweise statt für die ganze Datei beurteilt – das ist wichtig, weil ein technisches Dokument in solchen Schriften oft zur Hälfte aus lateinischen Zeichen besteht, voller Dateipfade und Klassennamen, und trotzdem von rechts nach links gelesen wird. Eingeschlossener Code bleibt davon ausgenommen und wird immer von links nach rechts gesetzt, und das Layout spiegelt sich korrekt: Aufzählungszeichen, Zitatbalken und Tabellenspalten wandern mit. Wo eine Schriftart kein Kursiv kennt, wird Hervorhebung durch Fettdruck statt Schrägstellung dargestellt.
Was nicht gemacht wird
LaTeX wird nicht gerendert. Ein Block zwischen Dollarzeichen wird als Text ausgegeben. Mermaid wird ebenfalls nicht gezeichnet: Ein Fence mit der Markierung mermaid erscheint als Codeblock mit Label. Chinesisch, Japanisch und Koreanisch liegen außerhalb der mitgelieferten Schriften, daher werden Zeichen in diesen Schriften als fehlend gemeldet statt geraten. Das sind Grenzen, keine Fehler, und sie sind hier dokumentiert, damit niemand sie erst nach dem Hochladen entdeckt.
Der praktische Teil
Laden Sie Dateien von Ihrem Gerät, aus Google Drive oder per Link hoch. Markdown-Dateien werden unter allen gängigen Endungen akzeptiert, ebenso wie reiner Text. Papierformate: A3, A4, A5, Letter, Legal oder Tabloid, Hoch- oder Querformat, mit schmalen, normalen oder breiten Rändern. Seitenzahlen und Syntaxhervorhebung sind standardmäßig aktiviert, können aber abgewählt werden. Laden Sie eine Datei hoch, erhalten Sie ein PDF zurück; mehrere Dateien kommen als ZIP oder – wenn gewünscht – als zusammengeführtes PDF mit durchgehender Seitennummerierung. Der Text bleibt echter Text, kann also ausgewählt, durchsucht und kopiert werden, statt als Bild der Wörter zu enden.
Was Sie bekommen
- Tabellen, die innerhalb der Ränder bleiben, mit Kopfzeile auf jeder Seite, auf der sie erscheinen
- Syntaxhervorgehobener Code mit umgebrochenen langen Zeilen statt abgeschnittenen
- Bilder, die in die Datei eingebettet sind, auch die aus rohem HTML
- Einen Lesezeichenbaum aus Ihren Überschriften und ein klickbares Inhaltsverzeichnis, wenn Sie es wünschen
- Schriften, die im PDF eingebettet sind, sodass die Datei auf jedem Gerät gleich aussieht
- Einen schriftlichen Bericht über alles, was der Konverter nicht erledigen konnte, inklusive fehlender Zeichen und Bilder
Wie geht es weiter?
Sie arbeiten stattdessen mit einer Word-Datei? Word zu PDF nimmt denselben Weg aufs Papier. Fügen Sie das Ergebnis mit dem Rest eines Berichts zusammen mit PDF zusammenführen. Und verkleinern Sie die Dateigröße vor dem Versenden mit PDF komprimieren.