MD in PDF umwandeln

Wer in Markdown schreibt, muss das Ergebnis irgendwann an jemanden weitergeben, der keinen Editor mit Markdown-Vorschau öffnet — ein Pflichtenheft für einen Kunden, ein Vermerk für den Betriebsrat, eine README als Anhang für einen Wirtschaftsprüfer, eine Dokumentation für eine Revision. In deutschen Unternehmen landet vieles davon in einem Vorgang, der ein festes, druckbares Dokument verlangt, kein Repository, in dem jemand navigieren müsste.

Für genau diesen Übergabemoment ist diese Seite gedacht: aus dem, was im Editor lesbar aussieht, ein Dokument machen, das jeder öffnen, ausdrucken und ablegen kann — ohne dass die Empfängerin ein Konto braucht oder ein Werkzeug installieren muss.

Hier unterscheidet sich diese Umwandlung von jeder anderen Dokumentumwandlung auf dieser Seite. Eine Word-Datei kennt ihre Seitengröße, ihre Ränder und ihre Schriftarten; eine Markdown-Datei kennt nichts davon, weil das Format bewusst nur Struktur festhält und das Aussehen dem überlässt, was sie später darstellt.

Jede Entscheidung über die Seite — Größe, Rand, Schriftart, wo ein Seitenumbruch fällt — trifft deshalb der Konverter, keine steht in der Datei. Meistens ist das der Vorteil von Markdown: Dasselbe Dokument wird ohne Umschreiben zur Webseite, zur Präsentation und zum PDF. Der Preis dafür zeigt sich hier, weil ein Konverter ohne Markdown-Filter nichts zu rendern hat und die Zeichen deshalb einfach setzt, wie sie dastehen.

Jedes Zeichen der Datei erscheint auf der Seite, in derselben Schrift, in der Reihenfolge, in der es geschrieben wurde. Eine Zeile ## Anforderungen wird als ## Anforderungen gesetzt. Ein mit Bindestrich geschriebener Aufzählungspunkt bleibt eine Zeile, die mit einem Bindestrich beginnt. Ein Codeblock behält seine drei Backticks oben und unten, fett bleibt mit seinen vier Sternchen stehen. Nichts wird verworfen und nichts interpretiert, weil das Dokumentwerkzeug hinter dieser Umwandlung Text liest und nie einen Markdown-Filter bekommen hat.

Was dabei bleibt, ist Zeilenumbrüche, Leerzeilen und Einrückung — genau erhalten. Ein Dokument, dessen Wert in seinen Befehlen oder seiner Konfiguration liegt, wird dadurch zu etwas Brauchbarem. Ein Dokument, dessen Wert in seiner Überschriftenhierarchie liegt, nicht — die Antwort dort ist, das Markdown im Werkzeug zu rendern, in dem es geschrieben wurde, und das PDF von dort aus zu drucken. Diese Umwandlung ist zum Fixieren des Textinhalts gedacht, nicht zum Setzen eines Layouts.

Eine Markdown-Datei mit sechs Diagrammen enthält kein einziges Bild. Sie enthält sechs Pfade, und die Bilder liegen daneben, auf der Festplatte oder auf einem Server. Das überrascht bei der ersten Umwandlung fast immer, und es ist der häufigste Grund für Lücken im fertigen PDF.

Die Lösung liegt darin, die Pfade vorher auflösbar zu machen. Relative Pfade müssen auf Dateien zeigen, die tatsächlich mitgeliefert werden; feste Webadressen setzen einen erreichbaren Server voraus. Sind die Bilder der eigentliche Inhalt des Dokuments, ist das der Punkt, an dem es sich lohnt, genau zu arbeiten — nicht an einer Einstellung auf dieser Seite.

Viele Markdown-Dateien beginnen mit einem Block, der von drei Bindestrichen eingerahmt ist und Titel, Datum und Schlagworte enthält. Statische-Seiten-Generatoren, Dokumentationswerkzeuge und Notiz-Apps lesen das als Metadaten und entfernen es, bevor überhaupt etwas gerendert wird.

Diese Umwandlung kennt die Konvention nicht und setzt den Block wie alles andere, sodass das PDF mit drei Bindestrichen und einer Liste von Schlüssel-Wert-Paaren beginnt, bevor der eigentliche Text anfängt. Den Block vor dem Umwandeln zu löschen ist die ganze Lösung — am besten in einer Kopie, damit das Original in dem Werkzeug weiterfunktioniert, das es geschrieben hat.

Die ursprüngliche informelle Beschreibung von Markdown aus dem Jahr 2004, CommonMark als die präzise Spezifikation, der die meisten Werkzeuge heute folgen, und die Erweiterungen wie Pipe-Tabellen, Aufgabenlisten, Fußnoten und Durchstreichen, die praktisch jeder verwendet — normalerweise entscheidet genau das, wie ein Dokument beim Rendern aussieht.

Auf dieser Seite ist das keine Frage. Nichts hier implementiert eine dieser Erweiterungen, auch nicht den Kern, also werden eine GitHub-Tabelle und eine CommonMark-Überschrift gleich behandelt — als Textzeilen. Immerhin ist das berechenbar: Es gibt keine Variante zu erraten und keinen Renderer zu testen, und was im Editor bei ausgeschalteter Syntaxhervorhebung zu sehen ist, ist auch das, was im PDF landet.

Eine mit Pipes geschriebene Tabelle kommt als genau die Zeilen aus Pipes und Bindestrichen an, die getippt wurden — jede Zeile für sich, in derselben Schriftart wie der Fließtext. Pipe-Tabellen sind eine GitHub-Erweiterung und kein Teil von CommonMark, aber das ist hier nicht der Grund: Nichts in dieser Umwandlung liest überhaupt Markdown.

Wer eine Tabelle im PDF tatsächlich als Tabelle braucht, kommt an diesem Punkt nicht vorbei, ohne in einem Editor zu rendern und von dort zu drucken. Für eine Konfigurationsliste oder eine kurze Übersicht mit wenigen Spalten reicht der reine Text meist trotzdem aus — für eine Vergleichstabelle mit vielen Spalten sieht das Ergebnis dagegen kaum noch nach einer Tabelle aus.

Zeilenumbrüche und Einrückung bleiben in einem Codeblock exakt erhalten, was für alles zählt, was jemand später abtippen oder ausführen wird, und die drei Backticks oben und unten stehen ebenfalls im PDF. Was fehlt, ist jede optische Unterscheidung vom übrigen Text — kein Rahmen, keine Hinterlegung, keine Syntaxfarben, weil das alles von einem Renderer hinzugefügt wird und nicht in der Datei selbst steht.

Für ein Konfigurationsbeispiel oder ein Kommandozeilenprotokoll ist das ausreichend, weil die Struktur zählt und nicht die Farbe. Für ein längeres Quellcode-Listing, das jemand lesen und nicht nur abtippen soll, ist ein PDF aus einer IDE mit eingeschalteter Hervorhebung die bessere Wahl.

Weil das Publikum nicht man selbst ist. Ein Kunde, eine Anwältin, ein Gremium oder eine Revisionsstelle will ein Dokument öffnen, ausdrucken, herumreichen und ablegen können — kein Programm, das die Maschine der Empfängerin in einem Code-Editor öffnen will, und kein Repository, in dem man erst navigieren muss. Die Rauten wandern mit, deshalb ist das hier eine fixierte Kopie und keine ausgearbeitete Präsentation.

Ein PDF friert außerdem den Zustand ein. Eine README ändert sich jede Woche; ein PDF davon zeigt, was an dem Tag stimmte, an dem es an etwas angehängt wurde — genau das, was eine Prüfung, eine Einreichung oder ein Vertragsanhang braucht. In Markdown weiterschreiben und erst im Moment des Bedarfs exportieren ist der richtige Ablauf.

HTML, wenn das Ziel eine Webseite oder eine Dokumentationsseite ist — Markdown wurde als Kurzschrift dafür entworfen, und die Umwandlung dorthin ist näher an einer Übersetzung als an diesem Setzen als Text.

DOCX in einem konkreten, häufigen Fall: Die Empfängerin akzeptiert nur eine Word-Datei und will Änderungen nachverfolgen können. Markdown hat keinen eigenen Überarbeitungs-Workflow, deshalb geht ein Dokument, das eine Kommentarrunde durchläuft, besser als DOCX hinaus und kommt von dort zurück — PDF ist für die fertige Fassung gedacht. Auch DOCX läuft über dasselbe Werkzeug, das Markup landet also auch dort als reiner Text; der Unterschied ist nur, dass eine Prüferin eine Überschrift im Word-Dokument reparieren kann und in einem PDF nicht.

Anders als die meisten Umwandlungen auf dieser Seite läuft diese nicht im eigenen Browser, weil dafür ein vollständiges Dokumentwerkzeug nötig ist. Die Datei reist über eine verschlüsselte Verbindung zu einem Container ohne Zugang zum offenen Internet, wird dort gesetzt und sofort nach der Umwandlung gelöscht.

Das ist die ehrliche Ausnahme von der sonst üblichen Regel dieser Seite, und sie steht hier bewusst so, statt sie zu verschweigen: Wer sensible Inhalte in Markdown geschrieben hat, sollte diesen einen Umstand kennen, bevor die Datei losgeschickt wird.