Daripada Markdown ke PDF dan Kembali: Apa yang Dikekalkan oleh Penukaran Format
Markdown↔PDF mengekalkan tajuk, senarai, dan jadual ringkas lebih baik daripada piksel. Fon, penomboran, susun atur tidak bertahan dalam pusingan tanpa kehilangan.
Markdown dan PDF mengoptimumkan kontrak yang berbeza. Markdown ialah struktur yang mesra kawalan versi. PDF ialah perihalan halaman yang tetap. Menukarnya ke satu arah dan kembali semula memang berguna; namun ia bukan kitaran arkib tanpa kehilangan.
Markdown ke PDF: struktur menjadi halaman
Markdown ke PDF (POST /api/v1/convert/markdown/pdf) menerima fail .md atau ZIP yang mengandungi Markdown. Muat naik yang bukan Markdown dan bukan ZIP ditolak. UTF-8 diperlukan untuk input .md biasa. Pipeline ini menghasilkan Markdown sebagai HTML dengan jadual, coretan, dan senarai tugasan didayakan, membalut HTML itu dalam CSS berorientasikan cetakan (termasuk susunan fon berbilang skrip dan RTL apabila bahasa Arab dikesan), kemudian mencetaknya ke PDF dengan WeasyPrint.
Apa yang cenderung bertahan dalam laluan ke hadapan:
- Tajuk, perenggan, senarai, dan jadual Markdown yang ringkas
- Teks berbilang skrip yang boleh disusun atur oleh laluan HTML (CJK, Latin, dan skrip lain yang diliputi CSS cetakan)
- PDF yang boleh dicetak dan dikongsi untuk aliran kerja docs-as-code
Apa yang tidak bertahan:
- Fon tema penyunting anda sebagai padanan yang dijamin dalam setiap pembaca
- Pemotongan baris skrin yang tepat daripada fail
.md - Ciri Markdown interaktif yang tiada padanan dalam PDF (kotak semak langsung, bahagian boleh dilipat, pautan wiki)
Input ZIP ialah untuk menggabungkan Markdown dengan aset yang boleh diselesaikan oleh laluan HTML di sebelah dokumen. Anggapnya sebagai kemudahan pembungkusan, bukan jaminan bahawa setiap imej relatif atau rujukan CSS akan kelihatan sama dalam setiap pembaca.
PDF ke Markdown: lapisan teks masuk, Markdown keluar
PDF ke Markdown (POST /api/v1/convert/pdf/markdown) mengekstrak kandungan tekstual ke Markdown melalui pdf-inspector. Responsnya ialah text/markdown yang dimuat turun sebagai fail .md. PDF digital dengan lapisan teks yang bersih menukar paling baik. Halaman imbasan tanpa lapisan teks menghasilkan Markdown yang kosong atau tidak berguna sehingga anda menjalankan OCR terlebih dahulu, dan OCR di tapak ini juga memulangkan Markdown, bukan lapisan PDF yang boleh dicari.
Jangkakan:
- Tajuk dan perenggan apabila heuristik saiz fon berfungsi dengan betul (anda mungkin masih perlu menomborkan semula tahap
#dengan tangan) - Jadual sebagai jadual Markdown apabila pengenalan berjaya; susun atur berbilang lajur mungkin dijadikan linear kepada susunan bacaan yang berbeza
- Pengepala dan pengaki yang berulang pada setiap halaman (pangkas dalam catatan)
- Imej dan persamaan dalam bentuk gambar yang tidak menjadi aset tempatan atau LaTeX secara automatik
Jika anda memerlukan prosa biasa tanpa heuristik tajuk, PDF ke Teks ialah ekstrak yang lebih rata. Eksport berbentuk jadual yang mengembalikan HTTP 204 bermakna tiada blok lajur dikesan; lihat Eksport jadual kosong (204).
Apa yang sebenarnya dibuktikan oleh pusingan pergi balik
| Bertahan dengan munasabah | Biasanya tidak |
|---|---|
| Perkataan, hierarki tajuk, struktur senarai | Geometri halaman yang tepat pada tahap piksel |
| Jadual ringkas sebagai teks | Fon dan kerning yang tepat |
| Draf yang berfungsi untuk Git atau ejen | Penomboran halaman yang sama seperti cetakan |
Melakukan pusingan pergi balik dua kali akan menyimpang. Markdown→PDF mengalir semula melalui WeasyPrint; PDF→Markdown membina semula struktur daripada heuristik pengekstrakan. Tiada langkah yang menyimpan perantaraan tanpa kehilangan bagi model susun atur format yang satu lagi.
Pilih arah kanonik
Jika anda memerlukan susun atur cetakan sebagai sistem rekod, simpan PDF dan anggap Markdown sebagai eksport atau suapan ejen. Jika anda memerlukan perbezaan, semakan kod, dan pengambilan oleh ejen, utamakan Markdown dan anggap PDF sebagai langkah penerbitan. Jangan simpan kedua-duanya sebagai “sumber kebenaran” yang setara lalu mengharapkannya kekal sama selepas suntingan.
Gelung docs-as-code yang praktikal: sunting Markdown dalam Git → Markdown ke PDF untuk artifak yang boleh dikongsi → elakkan PDF→Markdown→PDF sebagai tabiat harian. Gunakan PDF→Markdown apabila anda mewarisi PDF digital dan memerlukan teks untuk ejen, kemudian anggap Markdown itu sebagai draf baharu, bukan sebagai jaminan penomboran halaman asal.
Fail yang disulitkan memerlukan Buang kata laluan yang dibenarkan sebelum mana-mana penukaran. Fail rosak yang tidak boleh dihuraikan perlu melalui Maklumat dokumen / Baiki PDF terlebih dahulu. Untuk laluan yang sama melalui HTTP, lihat Pembangun.