Chuyển Markdown sang PDF

Markdown nào, và nó trở thành gì

Markdown là một họ định dạng chứ không phải một đặc tả duy nhất. Phần lõi chung — tiêu đề, nhấn mạnh, danh sách, liên kết, hình ảnh, trích dẫn, khối code — giống nhau ở mọi nơi, còn ngoài phần đó thì mỗi bản triển khai một khác. Những gì được hỗ trợ ở đây là bộ mở rộng được thống nhất rộng rãi: bảng, khối code có tô màu cú pháp, danh sách việc cần làm, gạch ngang chữ, chú thích cuối trang và front matter. Bộ này bao quát gần như mọi thứ người ta viết, và nên biết trước ranh giới thay vì phát hiện ra nó sau.

Tiêu đề trở thành cấu trúc PDF thực sự chứ không chỉ là chữ to hơn: chúng mang cấp độ dàn ý, nên PDF có thanh bookmark để điều hướng. Liên kết trở thành chú thích liên kết hoạt động được. Khối code được đặt bằng phông chữ đơn cách có tô màu, đó là khác biệt giữa một tài liệu dễ chịu khi đọc và một bức tường màu xám. Khổ giấy và lề được chọn cho việc đọc thay vì kế thừa, vì một file Markdown không có quan điểm gì về giấy.

Ảnh phải truy cập được, và đây là điều gây thất vọng phổ biến nhất. Một file Markdown tham chiếu tới hình ảnh chứ không chứa chúng, nên một đường dẫn tương đối chỉ hoạt động nếu ảnh được thả vào cùng file, và một địa chỉ web chỉ hoạt động nếu máy chủ đó cho phép trang khác tải ảnh về. Ảnh không tìm thấy sẽ được ghi chú trong PDF thay vì để lại một khoảng trống im lặng, nên một sơ đồ bị thiếu sẽ hiện rõ chứ không phải thứ bạn chỉ nhận ra sau khi đã gửi tài liệu đi.

Có hai thứ được cố ý hiển thị dưới dạng code thay vì dựng hình. Công thức toán viết bằng ký hiệu LaTeX và sơ đồ Mermaid đều cần bộ dựng hình riêng, và dựng sai còn tệ hơn hiển thị mã nguồn — một phương trình dựng sai là sai theo cách không ai nhìn ra. HTML thô bên trong Markdown được xử lý cho định dạng nội dòng đơn giản chứ không cho bố cục, vì một khối markup tùy ý không có chỗ trong tài liệu được chia trang.

Khi bạn cần công cụ khác

Pandoc là công cụ nghiêm túc cho việc này và nó miễn phí. pandoc doc.md -o doc.pdf --pdf-engine=xelatex dàn trang qua LaTeX, cho ra kết quả thực sự đẹp với ngắt âm tiết chuẩn, kiểm soát dòng lẻ và mục lục thực thụ — và với một template, bạn kiểm soát mọi khía cạnh của thiết kế. Nó cũng dựng đúng công thức toán LaTeX, đúng là khoảng trống cụ thể của trang này. Cái giá là phải cài một bản phân phối TeX, vốn không hề nhỏ.

Với tài liệu kỹ thuật thay vì một văn bản dùng một lần, một trình tạo trang tĩnh hoặc mdBook cho ra thứ tốt hơn PDF: tìm kiếm được, liên kết được, và đọc được trên điện thoại. Hãy chuyển sang PDF khi tài liệu cần in, đính kèm hoặc lưu trữ — và dù thế nào cũng giữ Markdown làm bản gốc, vì đó là phiên bản chỉnh sửa được và so sánh khác biệt được.