Chuyển Markdown sang HTML

Đoạn HTML hay trang hoàn chỉnh, và bạn cần cái nào

Có hai kiểu đầu ra hữu ích và chúng không thay thế được cho nhau. Đoạn HTML chỉ là phần mã đã chuyển đổi — tiêu đề, đoạn văn, danh sách, liên kết — không có phần vỏ tài liệu, đúng thứ bạn cần khi kết quả được đưa vào một mẫu giao diện, một ô nội dung trong CMS hoặc một trang khác. Trang hoàn chỉnh thêm doctype, phần head, khai báo bảng mã ký tự và một stylesheet, nên tự mở được và trông ra dáng một trang web. Dán trang hoàn chỉnh vào CMS sẽ thành một tài liệu nằm trong tài liệu; mở đoạn HTML trong trình duyệt thì chỉ thấy chữ trơn không định dạng.

Quá trình chuyển đổi hỗ trợ bộ Markdown mở rộng được thống nhất rộng rãi: tiêu đề, nhấn mạnh, danh sách, liên kết, ảnh, trích dẫn khối, bảng, khối code có tô màu cú pháp, danh sách công việc, chữ gạch ngang và chú thích cuối trang. Tiêu đề được gán định danh lấy từ chính nội dung của nó, nên có thể liên kết thẳng tới — chính các liên kết neo này giúp tài liệu dài trở nên dễ dùng.

HTML thô bên trong Markdown được giữ nguyên, đây là một phần của đặc tả và bạn nên cân nhắc kỹ: nghĩa là một file Markdown từ nguồn không đáng tin có thể chứa thẻ script, và chuyển đổi nó sẽ tạo ra một trang mang theo script đó. Đừng bao giờ hiển thị Markdown của người lạ mà không lọc sạch HTML sau đó — việc chuyển đổi không phải là một hàng rào bảo mật và chưa bao giờ được thiết kế để làm việc đó.

Có hai thứ được cố ý xuất thành khối code thay vì hiển thị. Công thức toán viết bằng ký hiệu LaTeX cần một thư viện dàn trang, còn sơ đồ Mermaid cần một trình vẽ sơ đồ — mỗi thứ là một phụ thuộc khá nặng, và một phương trình hiển thị sai còn tệ hơn một phương trình hiện nguyên dạng code. Trang hoàn chỉnh dùng phông chữ hệ thống thông thường thay vì tải phông về, nên hoạt động cả khi offline và trông hơi khác nhau trên Windows, macOS và Linux.

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

Pandoc xử lý được những phần bị bỏ qua ở đây và còn nhiều hơn thế: pandoc in.md -o out.html --mathjax --standalone --toc hiển thị đúng công thức toán, tạo mục lục và nhận một mẫu giao diện để kết quả khớp với website của bạn. Nó còn chuyển đổi qua lại với khoảng bốn mươi định dạng khác, vì vậy rất đáng để cài một lần.

Nếu cần cả một website chứ không phải một file, hãy dùng trình tạo trang tĩnh thay vì chuyển từng trang một. Hugo, Eleventy, Jekyll và MkDocs biến một thư mục Markdown thành website có điều hướng, tìm kiếm và định dạng thống nhất, rồi tự dựng lại mỗi khi nguồn thay đổi — đó mới là việc thực sự cần làm khi bạn có nhiều hơn một tài liệu.