Từ Markdown sang PDF và ngược lại: chuyển định dạng giữ được gì
Chuyển Markdown↔PDF giữ được tiêu đề, danh sách và bảng đơn tốt hơn pixel; font, phân trang và bố cục chính xác thì không tồn tại qua một vòng khứ hồi.
Markdown và PDF phục vụ hai hợp đồng. Markdown là cấu trúc thuận lợi cho kiểm soát phiên bản. PDF là mô tả trang cố định. Chuyển một chiều rồi quay lại vẫn hữu ích, nhưng đó không phải một chu trình lưu trữ không mất mát.
Markdown sang PDF: cấu trúc biến thành trang
Markdown to PDF (POST /api/v1/convert/markdown/pdf) nhận một tệp .md hoặc một ZIP chứa Markdown. Những tệp tải lên không phải Markdown và không phải ZIP đều bị từ chối. Đầu vào .md thuần bắt buộc dùng UTF-8. Pipeline render Markdown thành HTML với bảng, gạch ngang và task list, bọc HTML đó trong CSS hướng bản in (gồm ngăn xếp font đa hệ chữ và RTL khi phát hiện tiếng Ả Rập), rồi in ra PDF bằng WeasyPrint.
Những gì thường sống sót:
- Tiêu đề, đoạn văn, danh sách và bảng Markdown đơn giản
- Chữ đa hệ chữ mà đường HTML bố cục được (CJK, Latin và những hệ chữ khác mà CSS in phủ tới)
- Một PDF in và chia sẻ được cho quy trình docs-as-code
Những gì không:
- Font theme của trình soạn thảo khớp chắc chắn trên mọi trình xem
- Ngắt dòng trên màn hình giống hệt tệp
.md - Tính năng Markdown tương tác không có tương đương PDF (checkbox sống, mục thu gọn, wiki link)
Đầu vào ZIP để đóng gói Markdown cùng tài nguyên mà đường HTML tìm được ngay cạnh tài liệu. Coi đó là tiện ích đóng gói, không phải bảo đảm mọi ảnh tương đối hay tham chiếu CSS hiển thị giống nhau trên mọi trình xem.
PDF sang Markdown: lớp chữ vào, Markdown ra
PDF to Markdown (POST /api/v1/convert/pdf/markdown) trích nội dung chữ thành Markdown qua pdf-inspector. Phản hồi có kiểu text/markdown, được tải về thành tệp .md. PDF gốc số với lớp chữ sạch chuyển đổi tốt nhất. Trang scan không có lớp chữ chỉ cho Markdown trống hoặc vô dụng cho tới khi bạn OCR trước; mà OCR ở đây cũng trả Markdown, không phải lớp chữ tìm kiếm được.
Điều nên chờ đợi:
- Tiêu đề và đoạn văn khi heuristic theo cỡ chữ kích hoạt đúng (bạn vẫn có thể phải đánh số lại các mức
#bằng tay) - Bảng thành bảng Markdown khi nhận dạng được; bố cục nhiều cột có thể bị tuyến tính hóa thành thứ tự đọc khác
- Header và footer chạy lặp lại mỗi trang (cần cắt bỏ sau)
- Ảnh và phương trình dạng ảnh không tự thành tài nguyên cục bộ hay LaTeX
Nếu cần văn xuôi thuần, không heuristic tiêu đề, PDF to Text là bản trích phẳng hơn. Xuất dạng bảng trả về HTTP 204 nghĩa là không phát hiện khối cột; xem Xuất bảng rỗng (204).
Một vòng khứ hồi chứng minh điều gì
| Sống sót ở mức chấp nhận | Thường không |
|---|---|
| Từ ngữ, phân cấp tiêu đề, cấu trúc danh sách | Hình học trang chính xác từng pixel |
| Bảng đơn giản dưới dạng chữ | Font và kerning chính xác |
| Một bản nháp dùng được cho Git hoặc agent | Phân trang giống hệt bản in |
Khứ hồi hai lần sẽ lệch. Markdown→PDF để WeasyPrint dàn lại dòng; PDF→Markdown dựng lại cấu trúc từ heuristic trích xuất. Không bước nào lưu bản trung gian không mất mát của mô hình bố cục định dạng kia.
Chọn một hướng chuẩn
Nếu bố cục in là hệ thống ghi nhận, hãy giữ PDF và coi Markdown là bản xuất hoặc nguồn cấp cho agent. Nếu cần diff, review code và nạp cho agent, hãy ưu tiên Markdown và coi PDF là bước xuất bản. Đừng lưu cả hai như “nguồn sự thật” ngang hàng rồi kỳ vọng chúng giống nhau sau chỉnh sửa.
Vòng docs-as-code thực tế: sửa Markdown trong Git → Markdown to PDF để có bản chia sẻ → tránh PDF→Markdown→PDF như thói quen hằng ngày. Dùng PDF→Markdown khi tiếp nhận PDF gốc số và cần chữ cho agent, rồi coi Markdown đó là bản nháp mới, không phải bảo đảm phân trang gốc.
Tệp mã hóa cần Unlock hợp lệ trước khi chuyển đổi. Tệp hỏng không parse được nên qua Get Info / Repair trước. Muốn dùng đúng những endpoint đó qua HTTP, xem Nhà phát triển.