Von Markdown zu PDF und zurück: Was die Konvertierung erhält

Markdown und PDF sind auf unterschiedliche Verträge optimiert. Markdown ist eine Struktur, die sich gut mit Versionskontrolle bearbeiten lässt. PDF ist eine feste Beschreibung von Seiten. Die eine Richtung und zurück zu konvertieren ist nützlich; es ist kein verlustfreier Zyklus für die Archivierung.

Markdown zu PDF: Aus Struktur werden Seiten

Markdown zu PDF (POST /api/v1/convert/markdown/pdf) nimmt eine Datei .md oder ein ZIP mit Markdown entgegen. Uploads, die weder Markdown noch ZIP sind, werden abgelehnt. Für reine .md-Eingaben ist UTF-8 erforderlich. Der Ablauf rendert Markdown mit Tabellen, Durchstreichungen und Aufgabenlisten zu HTML, hüllt das HTML in CSS für den Druck (einschließlich Schriftstapeln für mehrere Schriftsysteme und RTL, wenn Arabisch erkannt wird) und druckt es mit WeasyPrint in eine PDF.

Was den Vorwärtsdurchlauf meist übersteht:

• Überschriften, Absätze, Listen und einfache Tabellen aus Markdown
• Text in mehreren Schriftsystemen, den der Weg über HTML setzen kann (CJK, Latein und andere Schriftsysteme, die das CSS für den Druck abdeckt)
• eine druckbare, teilbare PDF für Abläufe mit Dokumentation als Code

Was nicht:

• die Schriften des Themas deines Editors als garantiert gleiche Darstellung in jedem Betrachter
• die genauen Zeilenumbrüche aus der Datei .md auf dem Bildschirm
• interaktive Funktionen von Markdown ohne Entsprechung in PDF (lebende Kontrollkästchen, ein- und ausklappbare Abschnitte, Wiki-Links)

Ein ZIP als Eingabe dient dazu, Markdown mit Bestandteilen zu bündeln, die der Weg über HTML neben dem Dokument auflösen kann. Behandle es als Bequemlichkeit beim Verpacken und nicht als Garantie, dass jedes relative Bild oder jeder Verweis auf CSS in jedem Betrachter gleich aussieht.

PDF zu Markdown: Textebene hinein, Markdown heraus

PDF zu Markdown (POST /api/v1/convert/pdf/markdown) extrahiert textuellen Inhalt über pdf-inspector zu Markdown. Die Antwort ist text/markdown und wird als Datei .md heruntergeladen. Digital erzeugte PDFs mit sauberer Textebene lassen sich am besten konvertieren. Gescannte Seiten ohne Textebene liefern leeres oder unbrauchbares Markdown, bis du zuerst OCR ausführst, und OCR auf dieser Website liefert ebenfalls Markdown und keine durchsuchbare Ebene in einer PDF.

Erwarte:

• Überschriften und Absätze, wenn die Heuristiken für die Schriftgröße greifen (die Stufen der # musst du trotzdem möglicherweise von Hand neu nummerieren)
• Tabellen als Markdown-Tabellen, wenn die Erkennung funktioniert; mehrspaltige Layouts können in einer anderen Lesereihenfolge linearisiert werden
• wiederholte Kopf- und Fußzeilen auf jeder Seite (nachträglich entfernen)
• Bilder und als Bilder vorliegende Gleichungen, die nicht automatisch zu lokalen Bestandteilen oder LaTeX werden

Brauchst du reinen Fließtext ohne Heuristiken für Überschriften, ist PDF zu Text die flachere Extraktion. Exporte in Form von Tabellen, die HTTP 204 zurückgeben, bedeuten, dass keine spaltenförmigen Blöcke erkannt wurden; siehe Leerer Export von Tabellen (204).

Was ein Durchlauf hin und zurück tatsächlich beweist

Zweimal hin und zurück läuft auseinander. Markdown zu PDF setzt WeasyPrint neu und PDF zu Markdown baut die Struktur aus Heuristiken der Extraktion neu auf. Keiner der Schritte speichert ein verlustfreies Zwischenergebnis des Layoutmodells des anderen Formats.

Eine kanonische Richtung wählen

Brauchst du das Layout für den Druck als führende Quelle, behalte die PDF und behandle Markdown als Export oder als Zufuhr für Agenten. Brauchst du Unterschiede, Codeprüfung und die Aufnahme durch Agenten, bevorzuge Markdown und behandle PDF als Schritt der Veröffentlichung. Bewahre nicht beide als gleichwertige „Quellen der Wahrheit“ auf und erwarte nicht, dass sie nach Änderungen identisch bleiben.

Ein praktischer Zyklus für Dokumentation als Code: Markdown in Git bearbeiten → Markdown zu PDF für das teilbare Ergebnis → PDF zu Markdown zu PDF nicht zur täglichen Gewohnheit machen. Nutze PDF zu Markdown, wenn du eine digital erzeugte PDF übernommen hast und Text für einen Agenten brauchst, und behandle dieses Markdown dann als neuen Entwurf und nicht als Garantie für die ursprünglichen Seitenumbrüche.

Verschlüsselte Dateien brauchen vor jeder Konvertierung ein berechtigtes Entsperren. Beschädigte Dateien, die sich nicht analysieren lassen, sollten zuerst über Get Info und Reparieren laufen. Dieselben Endpunkte über HTTP beschreibt Entwickler.