Dari Markdown ke PDF dan kembali: apa yang dipertahankan konversi format
Markdown dan PDF mempertahankan heading, daftar, dan tabel sederhana, tetapi font tepat, paginasi, dan tata letak tidak selamat dalam perjalanan bolak-balik.
Markdown dan PDF dioptimalkan untuk kontrak yang berbeda. Markdown adalah struktur yang ramah sistem kontrol versi. PDF adalah deskripsi halaman yang sudah tetap. Mengonversi ke satu arah lalu kembali memang berguna, tetapi itu bukan siklus arsip yang lossless.
Markdown ke PDF: struktur menjadi halaman
Markdown to PDF (POST /api/v1/convert/markdown/pdf) menerima berkas .md atau ZIP yang berisi Markdown. Unggahan yang bukan Markdown dan bukan ZIP akan ditolak. UTF-8 wajib untuk masukan .md biasa. Alur ini merender Markdown menjadi HTML dengan tabel, strikethrough, dan task list aktif, membungkus HTML itu dalam CSS berorientasi cetak (termasuk tumpukan font multiaksara dan RTL saat terdeteksi bahasa Arab), lalu mencetaknya ke PDF dengan WeasyPrint.
Yang cenderung bertahan pada arah maju:
- Heading, paragraf, daftar, dan tabel Markdown sederhana
- Teks multiaksara yang bisa ditata jalur HTML (CJK, Latin, dan aksara lain yang tercakup CSS cetak)
- PDF yang dapat dicetak dan dibagikan untuk alur kerja docs-as-code
Yang tidak bertahan:
- Font tema editor Anda sebagai kecocokan yang dijamin di setiap penampil
- Pemenggalan baris di layar persis seperti di berkas
.md - Fitur Markdown interaktif yang tidak punya padanan di PDF (kotak centang hidup, bagian yang bisa dilipat, tautan wiki)
Masukan ZIP dipakai untuk membundel Markdown bersama aset yang bisa ditemukan jalur HTML di samping dokumen. Perlakukan itu sebagai kemudahan pengemasan, bukan jaminan bahwa setiap gambar relatif atau referensi CSS akan tampil sama di semua penampil.
PDF ke Markdown: lapisan teks masuk, Markdown keluar
PDF to Markdown (POST /api/v1/convert/pdf/markdown) mengekstrak konten tekstual menjadi Markdown lewat pdf-inspector. Responsnya berupa text/markdown yang diunduh sebagai berkas .md. PDF born-digital dengan lapisan teks yang bersih menghasilkan konversi terbaik. Halaman hasil pindai tanpa lapisan teks menghasilkan Markdown kosong atau tidak berguna sampai Anda menjalankan OCR lebih dulu; dan OCR di situs ini juga mengembalikan Markdown, bukan lapisan PDF yang bisa dicari.
Perkirakan hal berikut:
- Heading dan paragraf saat heuristik ukuran font bekerja dengan benar (Anda mungkin tetap perlu menomori ulang tingkat
#secara manual) - Tabel menjadi tabel Markdown bila pengenalannya berhasil; tata letak banyak kolom bisa berubah menjadi urutan baca yang berbeda
- Header dan footer berjalan yang terulang di setiap halaman (pangkas setelahnya)
- Gambar serta persamaan yang berupa gambar tidak otomatis menjadi aset lokal atau LaTeX
Bila Anda membutuhkan prosa polos tanpa heuristik heading, PDF to Text adalah ekstraksi yang lebih datar. Ekspor berbentuk tabel yang mengembalikan HTTP 204 berarti tidak ada blok berkolom yang terdeteksi; lihat Ekspor tabel kosong (204).
Apa yang sebenarnya dibuktikan perjalanan bolak-balik
| Bertahan dengan wajar | Umumnya tidak bertahan |
|---|---|
| Kata, hierarki heading, struktur daftar | Geometri halaman yang presisi piksel |
| Tabel sederhana sebagai teks | Font dan kerning yang persis |
| Draf yang bisa dipakai di Git atau oleh agen | Paginasi yang identik dengan cetakan |
Menjalani perjalanan bolak-balik dua kali akan membuat hasilnya bergeser. Markdown→PDF mengalirkan ulang lewat WeasyPrint; PDF→Markdown membangun ulang struktur dari heuristik ekstraksi. Tidak ada langkah yang menyimpan bentuk antara yang lossless dari model tata letak format lainnya.
Pilih satu arah kanonik
Jika tata letak cetak harus menjadi acuan utama, simpan PDF-nya dan perlakukan Markdown sebagai hasil ekspor atau umpan untuk agen. Jika Anda membutuhkan diff, tinjauan kode, dan konsumsi agen, utamakan Markdown dan perlakukan PDF sebagai langkah penerbitan. Jangan menyimpan keduanya sebagai "sumber kebenaran" yang setara lalu berharap keduanya tetap identik setelah disunting.
Alur docs-as-code yang praktis: sunting Markdown di Git → jalankan Markdown to PDF untuk artefak yang bisa dibagikan → hindari menjadikan PDF→Markdown→PDF sebagai kebiasaan harian. Gunakan PDF→Markdown ketika Anda mewarisi PDF born-digital dan membutuhkan teks untuk agen, lalu perlakukan Markdown itu sebagai draf baru, bukan jaminan paginasi aslinya.
Berkas terenkripsi memerlukan Unlock yang sah sebelum salah satu konversi dijalankan. Berkas rusak yang tidak bisa diurai sebaiknya melewati Get Info / Repair lebih dulu. Untuk titik akhir yang sama lewat HTTP, lihat Developers.