Cách chuyển đổi Markdown (MD) sang PDF để xuất bản
Tại sao người viết Markdown cần đầu ra PDF
Markdown là định dạng được ưa chuộng cho các nhà văn kỹ thuật, nhà phát triển và blogger muốn tập trung vào nội dung mà không phải vật lộn với trình soạn thảo văn bản. Tệp tin nhỏ gọn, kiểm soát phiên bản hoạt động trơn tru và cú pháp dễ đọc ngay cả khi ở dạng thô. Vấn đề nảy sinh ngay khi bạn cần gửi tài liệu cho khách hàng, nộp báo cáo hoặc xuất bản một tài liệu hoàn chỉnh. Các tệp .md thuần túy hiển thị khác nhau trên mỗi trình soạn thảo, và hầu hết những người không rành kỹ thuật đều không biết cách mở chúng. PDF giải quyết vấn đề đó. Một tệp PDF hiển thị giống hệt nhau trên mọi thiết bị, nhúng phông chữ, giữ nguyên cấu trúc tiêu đề của bạn và có thể in mà không gặp bất ngờ về định dạng lại. Một đặc tả kỹ thuật dài 40 trang trông hoàn hảo trong VS Code có thể đến hộp thư của khách hàng dưới dạng một tệp tin duy nhất, độc lập mà họ có thể mở bằng bất kỳ trình duyệt hoặc trình đọc PDF nào mà không cần cài đặt gì. Quá trình chuyển đổi không phải lúc nào cũng đơn giản đâu nhé. Bản thân Markdown không có tiêu chuẩn cho việc ngắt trang, lề hoặc cỡ chữ — những quyết định đó thuộc về bất kỳ công cụ hiển thị nào xử lý nó. Khoảng cách giữa 'văn bản với dấu sao' và 'PDF sẵn sàng in ấn' chính xác là những gì hướng dẫn này đề cập, bao gồm những công cụ như CocoConvert phù hợp ở đâu và khi nào bạn có thể cần một công cụ chuyên biệt hơn.
Điều gì xảy ra trong quá trình chuyển đổi MD sang PDF
Hiểu rõ quy trình giúp bạn dự đoán và khắc phục các vấn đề về đầu ra. Chuyển đổi Markdown sang PDF thực chất là một quy trình hai bước ngầm định, ngay cả khi một công cụ ẩn cả hai bước này đằng sau một nút duy nhất. Bước một: Markdown được phân tích cú pháp thành một định dạng trung gian — hầu như luôn là HTML. Mỗi tiêu đề trở thành thẻ `<h1>` đến `<h6>`, văn bản in đậm trở thành `<strong>`, khối mã trở thành các phần tử `<pre><code>`, v.v. Chất lượng của bước này phụ thuộc vào loại Markdown mà trình phân tích cú pháp hỗ trợ. CommonMark là đặc tả được tiêu chuẩn hóa nhất. GitHub Flavored Markdown (GFM) bổ sung các bảng, danh sách công việc và gạch ngang. Nếu tài liệu của bạn sử dụng các tính năng GFM như bảng dạng pipe và công cụ chuyển đổi chỉ xử lý CommonMark, thì các bảng đó sẽ xuất hiện dưới dạng các ký tự pipe thô trong đầu ra. Bước hai: HTML được hiển thị thành PDF bằng cách sử dụng một công cụ trình duyệt không giao diện (các công cụ dựa trên Chromium như Puppeteer) hoặc một thư viện PDF chuyên dụng. Bước này áp dụng CSS cho kiểu chữ, khoảng cách và bố cục trang. Lề thường được đặt khoảng 20–25mm ở mỗi bên cho giấy A4 hoặc giấy letter. Các khối mã sẽ có phông chữ monospace. Nếu công cụ sử dụng một stylesheet mặc định hợp lý, kết quả sẽ trông chuyên nghiệp mà không cần bất kỳ cấu hình nào. Ý nghĩa thực tế: nếu đầu ra PDF của bạn trông không đúng, lỗi thường nằm ở một trong hai bước này — hoặc Markdown không được phân tích cú pháp chính xác, hoặc CSS được áp dụng trong quá trình hiển thị tạo ra khoảng cách hoặc lựa chọn phông chữ không mong muốn.
Sử dụng CocoConvert để chuyển đổi MD sang PDF nhanh chóng
Đối với các tài liệu đơn giản — tệp README, ghi chú cuộc họp, báo cáo ngắn, trang tài liệu — [công cụ chuyển đổi MD sang PDF](/convert/md-to-pdf) của CocoConvert sẽ hoàn thành công việc mà không yêu cầu cài đặt phần mềm hay kiến thức về dòng lệnh nào. Quá trình gồm ba bước. Đầu tiên, tải tệp .md của bạn lên bằng cách kéo thả vào công cụ chuyển đổi hoặc nhấp vào trình chọn tệp. Hỗ trợ các tệp lên đến 25 MB, bao gồm phần lớn các tài liệu Markdown (một tài liệu 10.000 từ không có hình ảnh nhúng thường dưới 100 KB). Thứ hai, nhấp vào Chuyển đổi. Công cụ phân tích cú pháp CommonMark và GFM, bao gồm các khối mã được bao quanh với gợi ý ngôn ngữ, bảng dạng pipe và HTML nội tuyến. Thứ ba, tải xuống tệp PDF kết quả. Đầu ra mặc định sử dụng khổ giấy A4 với lề 20mm, phông chữ sans-serif dễ đọc cho nội dung ở cỡ 11pt và tô sáng cú pháp trong các khối mã. Các tiêu đề có kích thước từ 24pt (H1) xuống 13pt (H6). Những cài đặt mặc định này hoạt động tốt cho hầu hết các tài liệu và báo cáo. Hãy thành thật về những hạn chế ở đây: CocoConvert hiện không hỗ trợ chèn CSS tùy chỉnh, xử lý YAML front matter hoặc ký hiệu toán học LaTeX (ví dụ, `$E = mc^2$` sẽ xuất hiện dưới dạng văn bản thô chứ không phải là một phương trình được hiển thị). Nếu tài liệu của bạn chứa các công thức toán học, bạn sẽ nhận được kết quả tốt hơn từ Pandoc với backend LaTeX hoặc từ các công cụ như trình chuyển đổi hỗ trợ MathJax. Tương tự, nếu bạn cần kiểm soát chính xác việc ngắt trang — ví dụ, buộc một trang mới trước mỗi H2 — một quy trình làm việc bằng dòng lệnh sẽ cho bạn nhiều quyền kiểm soát hơn.
Chuẩn bị tệp Markdown của bạn trước khi chuyển đổi
Chỉ vài phút chuẩn bị trước khi chuyển đổi sẽ giúp bạn tránh được những vấn đề đầu ra phổ biến nhất. **Kiểm tra cấu trúc tiêu đề của bạn.** Một tài liệu có nhiều tiêu đề H1 sẽ tạo ra một tệp PDF trong đó nhiều dòng chia sẻ cùng một cỡ chữ lớn, trông thiếu cấu trúc. Sử dụng một H1 duy nhất cho tiêu đề tài liệu, H2 cho các phần chính và H3 cho các phần phụ. Hầu hết các công cụ kiểm tra cú pháp Markdown (quy tắc markdownlint MD025) tự động gắn cờ nhiều H1. **Xử lý hình ảnh cẩn thận.** Nếu tệp .md của bạn tham chiếu hình ảnh bằng đường dẫn tương đối như ``, thì các đường dẫn đó sẽ bị lỗi khi tệp được tải lên một mình vào một công cụ chuyển đổi dựa trên web. Bạn có thể nhúng hình ảnh dưới dạng Base64 data URI trực tiếp vào Markdown, hoặc sử dụng URL tuyệt đối trỏ đến các hình ảnh có thể truy cập công khai (ví dụ: ``). Đối với một tài liệu có 5–10 hình ảnh, việc chuyển đổi sang Base64 thủ công rất tẻ nhạt — hãy cân nhắc nén tệp .md cùng với thư mục hình ảnh của nó nếu công cụ chuyển đổi của bạn hỗ trợ tải lên tệp nén, hoặc sử dụng một công cụ cục bộ như Pandoc cho các tài liệu nặng hình ảnh. **Xóa hoặc thay thế cú pháp không được hỗ trợ.** Nếu tệp của bạn sử dụng Hugo shortcodes, Obsidian callouts (`> [!NOTE]`), hoặc các tiện ích mở rộng không chuẩn khác, hãy loại bỏ chúng hoặc chuyển đổi chúng thành các định dạng Markdown tiêu chuẩn trước khi tải lên. Một Obsidian callout có thể được thay thế bằng một blockquote đơn giản; một thẻ Hugo `{{< figure >}}` có thể được thay thế bằng tham chiếu hình ảnh `![]()` tiêu chuẩn. **Kiểm tra ký tự kết thúc dòng.** Ký tự kết thúc dòng CRLF kiểu Windows đôi khi gây ra các vấn đề về khoảng cách đoạn văn trong một số trình phân tích cú pháp. Chạy tệp qua chuyển đổi `dos2unix` nhanh chóng, hoặc lưu với ký tự kết thúc dòng LF từ trình soạn thảo của bạn, sẽ loại bỏ biến số này.
Khi nào nên dùng Pandoc thay thế (hoặc song song với CocoConvert)
Pandoc là một công cụ dòng lệnh miễn phí, mã nguồn mở, xử lý việc chuyển đổi Markdown sang PDF với khả năng cấu hình cao hơn nhiều so với bất kỳ công cụ web nào. Biết khi nào nên dùng nó sẽ giúp bạn tiết kiệm thời gian. Cài đặt Pandoc và một bản phân phối LaTeX (TeX Live trên Linux/Mac, MiKTeX trên Windows), sau đó chạy: ``` pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in -V fontsize=12pt ``` Lệnh đơn này chuyển đổi `report.md` thành tệp PDF với lề 1 inch và văn bản nội dung 12pt. Thêm `--toc` sẽ tự động tạo mục lục. Cờ `-V` truyền các biến vào mẫu LaTeX — bạn có thể đặt `mainfont`, `monofont`, `papersize`, `linestretch` và hàng chục tham số khác. Đối với các tài liệu nặng về toán học, Pandoc với XeLaTeX là công cụ phù hợp — nó hiển thị các phương trình LaTeX một cách tự nhiên. Đối với các tài liệu yêu cầu trang bìa tùy chỉnh, tiêu đề và chân trang chạy, hoặc kiểm soát chính xác widow/orphan, một mẫu LaTeX sẽ cung cấp cho bạn toàn quyền kiểm soát về kiểu chữ. Đánh đổi là thời gian thiết lập. Cài đặt TeX Live tốn 3–5 GB dung lượng đĩa và 15–30 phút. Gỡ lỗi các lỗi mẫu LaTeX đòi hỏi sự quen thuộc với cú pháp LaTeX. Để chuyển đổi một tệp README một lần vào 11 giờ đêm trước thời hạn, CocoConvert là con đường nhanh hơn. Đối với một tài liệu kỹ thuật 200 trang sẽ được xuất bản hàng quý, việc đầu tư vào quy trình làm việc Pandoc + LaTeX sẽ mang lại hiệu quả sau lần xuất bản thứ hai hoặc thứ ba. Những công cụ này không loại trừ lẫn nhau. Một quy trình làm việc hợp lý: sử dụng CocoConvert để xem trước nhanh và chia sẻ bản nháp, sau đó chạy phiên bản cuối cùng qua Pandoc với một mẫu đã được hoàn thiện để xuất bản.
Khắc phục các sự cố chuyển đổi phổ biến
**Bảng xuất hiện dưới dạng văn bản thuần túy.** Điều này thường có nghĩa là công cụ chuyển đổi đang sử dụng trình phân tích cú pháp chỉ hỗ trợ CommonMark, không hỗ trợ bảng dạng pipe của GFM. Xác minh rằng cú pháp bảng của bạn là chính xác — mỗi hàng cần có cùng số ký tự pipe và hàng phân cách (hàng có dấu gạch ngang) phải có mặt. Nếu công cụ chuyển đổi hỗ trợ GFM, một bảng được định dạng đúng sẽ hiển thị; nếu không, hãy chuyển sang một công cụ khác hỗ trợ GFM, hoặc chuyển đổi bảng sang khối `<table>` HTML, mà hầu hết các trình phân tích cú pháp Markdown đều giữ nguyên. **Khối mã bị mất thụt lề.** Đây là một vấn đề về phông chữ — công cụ hiển thị PDF đã quay về sử dụng phông chữ có tỷ lệ cho mã. Kiểm tra xem công cụ chuyển đổi có áp dụng phông chữ monospace cho các phần tử `<pre>` hay không. Nếu bạn đang sử dụng Pandoc, hãy thêm `--variable monofont='Courier New'` để buộc một phông chữ monospace cụ thể. **Hình ảnh bị thiếu.** Hầu như luôn là vấn đề về phân giải đường dẫn. Xem phần chuẩn bị ở trên. Xác nhận rằng các URL hình ảnh trả về HTTP 200 và không bị ẩn sau xác thực. **Tệp PDF không có số trang.** Các công cụ chuyển đổi dựa trên web thường không thêm tiêu đề hoặc chân trang chạy vì làm như vậy yêu cầu các quy tắc CSS `@page` với hỗ trợ bộ đếm, mà không phải tất cả các công cụ PDF đều xử lý nhất quán. Nếu bạn cần số trang, Pandoc với backend LaTeX sẽ thêm chúng theo mặc định, hoặc bạn có thể xử lý hậu kỳ tệp PDF trong Adobe Acrobat (Tools > Edit PDF > Header & Footer > Add). **Các dòng dài trong khối mã tràn ra ngoài lề trang.** Đây là vấn đề về ngắt dòng. Trong CSS, `pre { white-space: pre-wrap; }` khắc phục điều này, nhưng bạn không thể chèn CSS vào hầu hết các công cụ chuyển đổi web. Giải pháp thay thế là ngắt dòng thủ công các dòng dài trong tệp nguồn của bạn trước khi chuyển đổi, giữ các dòng dưới 80–90 ký tự.
Chọn cài đặt phù hợp để xuất bản
Từ 'xuất bản' bao gồm nhiều loại đầu ra khác nhau, và các cài đặt phù hợp cũng khác biệt đáng kể giữa chúng. **Để phân phối qua web hoặc email:** Kích thước trang A4 hoặc US Letter, lề 20–25mm, văn bản nội dung 11–12pt. Nhúng tất cả các phông chữ để đảm bảo hiển thị nhất quán trên máy của người nhận. Nếu kích thước tệp quan trọng — ví dụ, bạn đang đính kèm vào một email với giới hạn 10 MB — hãy tránh nhúng các tệp hình ảnh lớn ở độ phân giải đầy đủ. Thay đổi kích thước hình ảnh thành 150–200 DPI trước khi đưa chúng vào nguồn Markdown. **Để in ấn:** Sử dụng ít nhất 300 DPI cho bất kỳ hình ảnh raster nào. Lề nên rộng hơn — 25–30mm — để tính đến việc đóng gáy nếu tài liệu sẽ được đóng ghim hoặc đóng bìa. Nếu in thông qua dịch vụ chuyên nghiệp, hãy hỏi xem họ có yêu cầu tuân thủ PDF/X-1a hoặc PDF/X-4 hay không; hầu hết các công cụ chuyển đổi web tạo ra PDF 1.4 hoặc 1.5 tiêu chuẩn, không phải các biến thể PDF/X dành cho sản xuất in ấn. **Đối với thiết bị đọc sách điện tử và máy tính bảng:** Hãy cân nhắc xem PDF có thực sự là định dạng phù hợp hay không. EPUB xử lý văn bản có thể điều chỉnh dòng tốt hơn trên màn hình nhỏ. Tuy nhiên, nếu PDF là bắt buộc, một kích thước trang nhỏ hơn (khoảng 6×9 inch, tương tự như một cuốn sách bìa mềm) sẽ mang lại trải nghiệm đọc tốt hơn trên máy tính bảng so với một trang A4 được thu nhỏ. **Đối với các cổng tài liệu kỹ thuật:** Nhiều nền tảng tài liệu (ReadTheDocs, GitBook, Docusaurus) có quy trình xuất PDF riêng được xây dựng trên Chromium hoặc WeasyPrint. Nếu bạn đã sử dụng một trong những nền tảng đó, tính năng xuất bản địa của họ sẽ tôn trọng chủ đề và cấu trúc điều hướng của trang web của bạn tốt hơn là chuyển đổi riêng lẻ từng tệp .md. Đối với hầu hết các nhu cầu xuất bản hàng ngày — chia sẻ một báo cáo hoàn chỉnh, phân phối một tài liệu đặc tả hoặc lưu trữ một tệp README — việc chuyển đổi trực tiếp thông qua [công cụ MD-to-PDF của CocoConvert](/convert/md-to-pdf) với các cài đặt mặc định sẽ tạo ra kết quả sạch, dễ đọc chỉ trong vòng chưa đầy một phút.