Van Markdown naar PDF en terug: wat formaatconversie behoudt
Markdown↔PDF houdt koppen, lijsten en eenvoudige tabellen beter vast dan pixels. Exacte fonts, paginering en opmaak gaan bij conversie verloren.
Markdown en PDF zijn geoptimaliseerd voor verschillende contracten. Markdown is een structuur die goed samengaat met versiebeheer. PDF is een vaste paginabeschrijving. Eén richting op converteren en weer terug is nuttig; het is geen verliesvrije cyclus voor archivering.
Markdown naar PDF: structuur wordt pagina's
Markdown to PDF (POST /api/v1/convert/markdown/pdf) accepteert een .md-bestand of een ZIP met Markdown erin. Bestanden die geen Markdown zijn en geen ZIP worden geweigerd. Voor gewone .md-invoer is UTF-8 vereist. De pijplijn zet Markdown om naar HTML met tabellen, doorhaling en takenlijsten ingeschakeld, wikkelt die HTML in CSS voor drukwerk (inclusief fontstacks voor meerdere schriften en RTL wanneer Arabisch wordt gedetecteerd) en drukt het geheel met WeasyPrint naar PDF af.
Wat de voorwaartse stap meestal overleeft:
- koppen, alinea's, lijsten en eenvoudige Markdown-tabellen
- tekst in meerdere schriften die het HTML-pad kan opmaken (CJK, Latijn en andere schriften die de CSS voor drukwerk ondersteunt)
- een printbare, deelbare PDF voor processen met documentatie als code
Wat niet:
- de themafonts van uw editor als gegarandeerd hetzelfde in elke viewer
- de exacte regelafbrekingen van het scherm uit het
.md-bestand - interactieve functies van Markdown zonder equivalent in PDF (live selectievakjes, inklapbare secties, wikilinks)
Een ZIP als invoer dient om Markdown te bundelen met bestanden die het HTML-pad naast het document kan vinden. Zie het als een gemak bij het verpakken, niet als garantie dat elke relatieve afbeelding of CSS-verwijzing er in elke viewer hetzelfde uitziet.
PDF naar Markdown: tekstlaag erin, Markdown eruit
PDF to Markdown (POST /api/v1/convert/pdf/markdown) haalt tekstuele inhoud via pdf-inspector naar Markdown. Het antwoord is text/markdown, gedownload als .md-bestand. Digitaal ontstane PDF's met een schone tekstlaag converteren het beste. Gescande pagina's zonder tekstlaag leveren lege of onbruikbare Markdown op tot u eerst OCR toepast; en OCR op deze site levert ook Markdown, geen doorzoekbare PDF-laag.
Verwacht:
- koppen en alinea's wanneer de heuristiek op fontgrootte goed aanslaat (u moet de niveaus van
#mogelijk nog met de hand hernummeren) - tabellen als Markdown-tabellen wanneer de herkenning werkt; indelingen met meerdere kolommen kunnen in een andere leesvolgorde terechtkomen
- kop- en voetteksten die op elke pagina terugkomen (schoon ze achteraf op)
- afbeeldingen en vergelijkingen als plaatjes die niet automatisch lokale bestanden of LaTeX worden
Hebt u platte tekst zonder heuristiek voor koppen nodig, dan is PDF to Text de vlakkere extractie. Tabelvormige exporten die HTTP 204 teruggeven, betekenen dat er geen kolomblokken zijn gedetecteerd; zie Empty table export (204).
Wat een heen-en-weer-conversie werkelijk aantoont
| Blijft redelijk behouden | Meestal niet |
|---|---|
| Woorden, hiërarchie van koppen, lijststructuur | Pixelperfecte paginageometrie |
| Eenvoudige tabellen als tekst | Exacte fonts en kerning |
| Een bruikbaar concept voor Git of agents | Identieke paginering bij drukwerk |
Twee keer heen en weer converteren veroorzaakt verschuiving. Markdown→PDF laat de tekst opnieuw door WeasyPrint vloeien; PDF→Markdown bouwt de structuur op uit heuristieken voor extractie. Geen van beide stappen bewaart een verliesvrije tussenstap van het opmaakmodel van het andere formaat.
Kies een vaste richting
Hebt u de drukwerkindeling nodig als het systeem dat als waarheid geldt, bewaar dan de PDF en behandel Markdown als export of als invoer voor agents. Hebt u verschillen, codebeoordeling en inname door agents nodig, kies dan Markdown en behandel PDF als de publicatiestap. Bewaar beide niet als gelijkwaardige “bronnen van waarheid” en verwacht niet dat ze na bewerkingen identiek blijven.
Een praktische lus voor documentatie als code: bewerk Markdown in Git → Markdown to PDF voor het deelbare artefact → vermijd PDF→Markdown→PDF als dagelijkse gewoonte. Gebruik PDF→Markdown wanneer u een digitaal ontstane PDF hebt geërfd en tekst voor een agent nodig hebt; behandel die Markdown dan als een nieuw concept, niet als garantie voor de oorspronkelijke paginering.
Versleutelde bestanden hebben een geautoriseerde Unlock nodig voordat u een van beide conversies uitvoert. Beschadigde bestanden die niet te parsen zijn, moeten eerst door Get Info / Repair. Voor dezelfde endpoints via HTTP, zie Developers.