Z Markdownu do PDF i z powrotem: co zachowuje konwersja formatu

Markdown i PDF optymalizują pod różne kontrakty. Markdown to struktura przyjazna kontroli wersji. PDF to stały opis strony. Konwersja w jedną stronę i z powrotem bywa użyteczna, ale nie jest bezstratnym cyklem archiwizacyjnym.

Markdown do PDF: struktura staje się stronami

Markdown do PDF (POST /api/v1/convert/markdown/pdf) przyjmuje plik .md albo archiwum ZIP zawierające Markdown. Pliki inne niż Markdown i ZIP są odrzucane. Dla zwykłego .md wymagane jest kodowanie UTF-8. Potok renderuje Markdown do HTML z włączonymi tabelami, przekreśleniem i listami zadań, opakowuje ten HTML w CSS przeznaczony do druku (między innymi w stosy fontów dla wielu pism oraz RTL, gdy wykryty zostanie arabski), a następnie drukuje do PDF przez WeasyPrint.

Co zwykle przetrwa przejście w tę stronę:

• nagłówki, akapity, listy i proste tabele Markdown,
• tekst w wielu pismach, które ścieżka HTML potrafi złożyć (CJK, łacina i inne pisma objęte CSS do druku),
• PDF nadający się do druku i udostępniania w procesach docs-as-code.

Czego nie:

• fonty motywu twojego edytora jako gwarantowane dopasowanie w każdej przeglądarce,
• dokładne łamanie wierszy z pliku .md widoczne na ekranie,
• interaktywne funkcje Markdown, które nie mają odpowiednika w PDF (żywe pola wyboru, zwijane sekcje, linki wiki).

Wejście w formie ZIP służy do spakowania Markdown razem z zasobami, które ścieżka HTML potrafi odnaleźć obok dokumentu. Traktuj je jako wygodę pakowania, a nie gwarancję, że każdy względny odnośnik do obrazu albo CSS będzie wyglądał identycznie w każdej przeglądarce.

PDF do Markdown: warstwa tekstu na wejściu, Markdown na wyjściu

PDF do Markdown (POST /api/v1/convert/pdf/markdown) wyciąga treść tekstową do Markdown przez pdf-inspector. Odpowiedź to text/markdown pobierany jako plik .md. Najlepiej konwertują się cyfrowe PDF-y z czystą warstwą tekstową. Zeskanowane strony bez warstwy tekstowej dają pusty albo bezużyteczny Markdown, dopóki nie uruchomisz najpierw OCR; a OCR w tym serwisie również zwraca Markdown, a nie przeszukiwalną warstwę PDF.

Czego się spodziewać:

• nagłówków i akapitów, gdy heurystyki rozmiaru fontu zadziałają poprawnie (poziomy # możesz nadal przenumerować ręcznie),
• tabel jako tabel Markdown, gdy rozpoznawanie się powiedzie; układy wielokolumnowe mogą się zlinearyzować w inną kolejność czytania,
• powtarzanych nagłówków i stopek na kolejnych stronach (przytnij je po konwersji),
• obrazów i równań zapisanych jako obrazki, które nie stają się automatycznie lokalnymi zasobami ani kodem LaTeX.

Jeśli potrzebujesz zwykłej prozy bez heurystyk nagłówków, PDF do tekstu daje bardziej płaski wynik. Eksport w formie tabeli, który zwraca HTTP 204, oznacza, że nie wykryto bloków kolumnowych; zobacz Pusty eksport tabeli (204).

Co naprawdę dowodzi podróż w obie strony

Dwukrotne przejście w obie strony będzie dryfować. Markdown→PDF przepływa ponownie przez WeasyPrint, a PDF→Markdown odbudowuje strukturę na podstawie heurystyk ekstrakcji. Żaden z tych kroków nie zapisuje bezstratnej reprezentacji pośredniej modelu układu drugiego formatu.

Wybierz kierunek kanoniczny

Jeśli układem wydruku ma być źródło prawdy, trzymaj PDF, a Markdown traktuj jako eksport albo kanał dla agenta. Jeśli potrzebujesz diffów, przeglądu kodu i wczytywania przez agenta, wybierz Markdown, a PDF traktuj jako krok publikacji. Nie przechowuj obu formatów jako równorzędnych „źródeł prawdy” i nie oczekuj, że po edycjach pozostaną identyczne.

Praktyczna pętla docs-as-code: edytuj Markdown w Git → Markdown do PDF na artefakt do udostępnienia → unikaj codziennego PDF→Markdown→PDF. Po PDF→Markdown sięgnij, gdy odziedziczyłeś cyfrowy PDF i potrzebujesz tekstu dla agenta; taki Markdown traktuj jako nowy szkic, a nie gwarancję oryginalnej paginacji.

Zaszyfrowane pliki wymagają uprawnionego odblokowania przed którąkolwiek konwersją. Uszkodzone pliki, które się nie parsują, najpierw przepuść przez Pobierz informacje / Napraw. Te same punkty końcowe przez HTTP opisuje Dla programistów.