Eine README lässt sich im Repository bequem prüfen. Dieselben Informationen werden für eine Besprechung, Übergabe oder Ablage jedoch oft als stabiles Dokument benötigt. Markdown in PDF umzuwandeln ist sinnvoll, wenn die Quelle einfacher Text bleiben und die Ausgabe feste Seiten, Ränder und auswählbaren Text besitzen soll. Die Aufgabe endet nicht mit einer Datei namens .pdf: Struktur, Links, Tabellen und Code müssen auch nach dem Seitenumbruch verständlich bleiben.
Dieser Leitfaden erstellt eine reproduzierbare README und wandelt sie mit dem Markdown-zu-PDF-Werkzeug um. UtilX verarbeitet die Eingabe im Browser und exportiert nur auf ausdrücklichen Wunsch. Das Beispiel enthält keine vertraulichen Daten und trennt klar zwischen Vorschau und Prüfung der fertigen PDF-Datei.
Das Dokument vor der Formatierung definieren
Markdown beschreibt Struktur durch Konventionen im Klartext. CommonMark unterscheidet Blöcke wie Überschriften, Absätze, Zitate, Listen, Trennlinien und Codeblöcke von Inline-Inhalten wie Links, Hervorhebung und Code. GitHub Flavored Markdown ergänzt Tabellen, Aufgabenlisten und Durchstreichung. Ein Konverter überträgt diese Strukturen in ein Seitenmodell; die flexible Breite eines Browsers kann er nicht exakt erhalten.
Bestimme zuerst Zweck und Leserschaft. In diesem Beispiel braucht ein Team eine offline verfügbare Freigabe-Checkliste. Die PDF soll auf A4 lesbar sein, anklickbare HTTPS-Links behalten, Code als Code zeigen und erledigte Aufgaben unterscheiden. Diese Anforderungen lassen sich prüfen. „Sieht überall identisch aus“ lässt sich nicht zusichern: Vorschau und PDF verwenden verschiedene Layoutsysteme, sodass Zeilen- und Seitenumbrüche abweichen können.
Ein vollständiges README-Beispiel
Erstelle release-readme.md mit dem folgenden synthetischen Inhalt. Er deckt die unterstützte Syntax ab, ohne entfernte Dateien vorauszusetzen:
# Atlas 1.4 Freigabe
**Verantwortlich:** Dokumentationsteam
*Zeitfenster:* 18. September 2026
~~Altes Ziel: 1.3~~
> Erst nach erfolgreicher Rollback-Prüfung freigeben.
## Checkliste
- [x] Übersetzungen einfrieren
- [ ] Paket veröffentlichen
- [x] Prüfsumme kontrollieren
- [ ] Versionshinweis kopieren
## Befehle
Zuerst `npm test`, danach:
~~~sh
npm run build
npm run smoke
~~~
## Umgebungen
| Name | URL | Team |
| --- | --- | --- |
| Staging | [Status](https://example.com/status) | Plattform |
| Produktion | ausstehend | Betrieb |
---
Siehe [Ablauf](https://example.com/runbook).
Die erwartete PDF enthält eine Hauptüberschrift, drei Metadaten — Verantwortliche, Zeitfenster und durchgestrichenes früheres Ziel —, ein Zitat, verschachtelte Aufgaben, Inline- und Blockcode, eine Tabelle mit drei Spalten, eine Trennlinie und zwei Links. Eine genaue Seitenzahl wird bewusst nicht genannt: Sie hängt von Papierformat, Rändern, Schriftgröße und Umbruch ab.
Schrittweise umwandeln und prüfen
Öffne das lokalisierte Werkzeug und füge das Beispiel ein oder importiere die .md-Datei. Die Quelle muss in UTF-8 unter 200 KiB bleiben; größere Eingaben werden vor dem Parsen abgewiesen. Prüfe in der Vorschau die Hierarchie und nicht die Seitengrenzen. Die Überschrift muss sich vom Fließtext abheben, offene und erledigte Aufgaben müssen unterscheidbar bleiben, Unterpunkte müssen ihrem Elternpunkt zugeordnet sein und die Tabelle muss drei Spalten besitzen.
Wähle A4, 20 mm Rand, 12 pt Text und Seitenzahlen. Gib der Datei einen aussagekräftigen Namen wie atlas-1-4-freigabe.pdf und starte den Export ausdrücklich. Eine Textänderung darf keinen Download auslösen. Öffne die gespeicherte PDF in einem separaten Reader. Markiere und kopiere einen Satz, um auswählbaren Text statt eines ganzseitigen Bildes zu bestätigen. Suche nach Rollback, aktiviere beide HTTPS-Links und vergrößere Befehlsblock und Tabelle.
Wiederhole die Ausgabe mit Letter, falls der Empfänger dieses Format druckt. Vergleiche Bedeutung und Lesbarkeit, nicht Koordinaten. Eine schmale Tabelle kann anders umbrechen; eine Überschrift kann auf die nächste Seite rutschen. Wird eine Zeile schwer lesbar, kürze Zellen oder stelle sie als Liste dar, bevor du das ganze Dokument verkleinerst.
Was die Optionen tatsächlich verändern
A4 und Letter haben unterschiedliche Maße. Derselbe Absatz kann daher verschieden viele Zeilen belegen. Die Ränder von 12, 20 und 28 mm verändern die verfügbare Schreibfläche. Die Schriftgrößen 10, 12 und 14 pt verändern Dichte und Lesbarkeit. Die Einstellungen wirken zusammen: Größere Ränder und größere Schrift führen zu früheren Umbrüchen und meist zu mehr Seiten.
Seitenzahlen sind ein optionaler Bestandteil der Ausgabe. Sie helfen bei der Besprechung einer festen Kopie, gehören aber nicht zu Markdown. Die PDF-Erzeugung ordnet den Inhalt einem festen Seitenformat zu und kann dynamische Zahlen in der Fußzeile platzieren. Das exportierte Dokument behält auswählbaren Text und unterstützte Links. Die Vorschau vermittelt Stil und Reihenfolge ehrlich, garantiert jedoch keine identische Paginierung.
Die erste Version unterstützt Überschriften, Absätze, Fettdruck, Kursivschrift, Durchstreichung, HTTP(S)- und mailto-Links, verschachtelte geordnete oder ungeordnete Listen, Aufgabenlisten, Zitate, Trennlinien, Inline- und eingezäunten Code sowie GFM-Tabellen. Diese Liste ist wichtig, weil Markdown-Dialekte voneinander abweichen. Eine Repository-Erweiterung, die an einem Ort funktioniert, wird nicht automatisch von jedem Konverter verstanden.
Häufige Fehler beheben
Geht eine Listenebene verloren, prüfe Einrückung und Leerzeilen um benachbarte Blöcke. Erscheint eine Tabelle als wörtliche Folge senkrechter Striche, braucht sie eine Kopfzeile, eine Trennzeile und in jeder Zeile dieselben logischen Spalten. Übernimmt ein Codeblock nachfolgenden Text, schließe ihn mit demselben Zeichen und mindestens derselben Anzahl wie beim Öffnen. Diese Prüfungen folgen Blockregeln statt der optischen Ausrichtung eines einzelnen Editors.
Entfernte Bilder und Verweise auf lokale Dateien werden nicht geladen. Der Konverter zeigt Alternativtext und eine Warnung, damit die Auslassung sichtbar bleibt. Schreibe aussagekräftigen Alt-Text und liefere freigegebene Bilder separat, falls der endgültige Ablauf sie verlangt. Rohes HTML wird mit Warnung wörtlich dargestellt und nicht ausgeführt. HTML-Tags sind kein Ersatz für eine nicht unterstützte Gestaltung.
Stoppt der Export, prüfe zuerst die UTF-8-Größe. Ein großes Dokument in sinnvolle Kapitel zu teilen ist sicherer, als Warnungen oder Code ungezielt zu löschen. Funktioniert ein Link nicht, bestätige den Anfang https://, http:// oder mailto: und teste neben der Vorschau auch die exportierte PDF.
Entscheidungen für eine dauerhafte Übergabe
Behalte Markdown als bearbeitbare Quelle und behandle die PDF als datierte Ausgabe. Dokumentiere Papier, Rand, Schriftgröße, Seitenzahlen und Werkzeugdatum beim Freigabeprozess. Andere können den Export dann reproduzieren, statt eine undurchsichtige PDF zu bearbeiten. Bei gelenkten Dokumenten gehören Quellrevision und exportierte Datei zusammen.
Ordne Überschriften sinnvoll und schreibe beschreibende Linktexte. Verlasse dich beim Aufgabenstatus nicht allein auf Farbe. Halte Codezeilen angemessen kurz und Tabellen kompakt; beide Strukturen haben eine natürliche Breite, die auf Papier nicht immer passt. Eine Liste ist bei langen Texten oft robuster als eine Tabelle. Lies die PDF vor der Weitergabe bei normaler Vergrößerung und benutze Auswahl oder Suche, nicht nur Miniaturen.
Die Verarbeitung im Browser vermeidet, dass der eingegebene Markdown-Text für diese Konvertierung an den Anwendungsserver gesendet werden muss. Die heruntergeladene Datei gelangt dennoch in den normalen Speicherablauf von Browser und Betriebssystem. Wende dieselben Regeln für Einstufung und Weitergabe wie bei anderen exportierten Dokumenten an.
Grenzen des Konverters
Die erste Version rendert keine Mathematik, Mermaid-Diagramme, benutzerdefiniertes HTML oder ausführbare Inhalte. Sie lädt weder entfernte Bilder noch referenzierte Dateien. Sie verspricht keine pixelgleiche Vorschau und PDF-Paginierung, Archivkonformität, barrierefreies Tagged PDF, digitale Signaturen, Verschlüsselung oder Unterstützung projektspezifischer Plugins. Eine geöffnete PDF ist nicht automatisch barrierefrei, freigegeben oder vollständig.
Komplexe Tabellen können trotz gültiger Syntax schlecht lesbar bleiben. Um Abschneiden zu verhindern, wird die Einrückung in der PDF nach sechs verschachtelten Listenebenen nicht weiter erhöht; der übrige Inhalt bleibt erhalten. Würde die verfügbare Breite eine Spalte auf weniger als 25 pt reduzieren, wird die Tabelle mit einer Meldung abgewiesen. Teile dann Spalten auf oder verkleinere die Ränder, statt eine unlesbare Ausgabe zu erzwingen.
Sehr lange ungetrennte Zeichenfolgen und Codezeilen können ungünstig umbrechen. Der Export fügt Umbruchmöglichkeiten ein, und manche PDF-Reader können beim Kopieren über solche Stellen Leerzeichen einfügen. Muss ein Befehl exakt sein, kopiere die lange Zeile aus der PDF und vergleiche sie vor der Ausführung Zeichen für Zeichen mit der Markdown-Quelle. Reader behandeln auch Links und Schriften unterschiedlich. Prüfe die exportierte Datei in der vorgesehenen Umgebung und verwende ein spezialisiertes Publikationsverfahren, wenn exakte Typografie, erweiterte Barrierefreiheit oder Konformität erforderlich sind.
Abschließende Prüfliste
Bestätige UTF-8 und höchstens 200 KiB. Vergleiche Überschriften, Hervorhebung, Durchstreichung, Links, verschachtelte Listen und Aufgaben, Zitate, Trennlinien, Code und Tabellen mit der beabsichtigten Aussage. Prüfe jede Bildwarnung und jeden Hinweis auf wörtliches HTML. Exportiere mit A4 oder Letter, 12, 20 oder 28 mm Rand, 10, 12 oder 14 pt Text sowie der vereinbarten Seitenzahloption.
Öffne die heruntergeladene PDF unabhängig. Markiere und kopiere Text, suche einen bekannten Ausdruck, folge wichtigen Links und kontrolliere Tabellenspalten, Code und Seitenübergänge. Vergleiche Inhalt und Hierarchie mit der README, ohne identische Vorschaupaginierung zu verlangen. Bewahre schließlich Quelle und Einstellungen mit der geprüften PDF auf, damit eine andere Person das Ergebnis reproduzieren kann.
Quellen: CommonMark-Spezifikation, GitHub-Flavored-Markdown-Spezifikation und pdfmake-Dokumentation zur Dokumentdefinition.