Xem trước Markdown

Markdown nào, và vì sao HTML được làm sạch

Markdown là một họ ngôn ngữ chứ không phải một đặc tả duy nhất, và biến thể được dùng ở đây là bộ Markdown kiểu GitHub được thống nhất rộng rãi: tiêu đề, nhấn mạnh, danh sách, liên kết, hình ảnh, trích dẫn, bảng, khối mã 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à liên kết tự động. Đó là thứ gần như ai cũng viết và là những gì một README sẽ chứa. Các biến thể lạ hơn và plugin tùy chỉnh mà một trang cụ thể thêm vào — khối admonition, shortcode, templating — thì không, nên một tài liệu viết cho một trình tạo trang cụ thể có thể hiển thị nguyên văn một phần cú pháp của nó.

HTML thô được hiển thị nhưng đã được làm sạch trước, và đây là phần đáng hiểu rõ. Markdown cố ý cho phép HTML bên trong, nghĩa là một file Markdown từ bất cứ đâu cũng có thể chứa thẻ script, trình xử lý sự kiện nội tuyến, iframe hoặc liên kết javascript:. Hiển thị nguyên trạng sẽ chạy mã của người lạ trong phiên của bạn chỉ vì bạn dán README của họ vào để xem. Mọi thứ có thể thực thi đều bị loại bỏ trước khi hiển thị, nên định dạng được giữ lại còn mã thì không.

Đó là một bài học chung chứ không phải chi tiết riêng của trang này. Bất kỳ hệ thống nào hiển thị Markdown do người dùng cung cấp — ô bình luận, wiki, phiếu hỗ trợ — đều đang hiển thị HTML do người dùng cung cấp nếu không làm sạch, và câu “chỉ là Markdown thôi mà” chính là cách điều đó bị bỏ qua. Chuyển đổi Markdown không phải là ranh giới bảo mật; bước làm sạch mới là.

Thứ bạn nhận được là bản xem trước nội dung, không phải của một trang cụ thể nào. GitHub, GitLab và mỗi trình tạo tài liệu đều áp dụng stylesheet, anchor tiêu đề và phần mở rộng riêng, nên cùng một file trông khác nhau ở mỗi nơi — cấu trúc hiển thị ở đây là phần tất cả đều thống nhất. Không tải gì về, nên ảnh được tham chiếu bằng địa chỉ web chỉ tải được nếu máy chủ đó cho phép, còn đường dẫn tương đối đến file trong repository thì hoàn toàn không phân giải được.

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

Với một README bạn đang thực sự viết, hãy xem trước ở nơi nó sẽ nằm. Trình soạn thảo của chính GitHub xem trước với đúng cách hiển thị, phần mở rộng và anchor của nó, và GitHub CLI — gh markdown-preview — làm điều đó ngay trên máy bạn với cùng trình hiển thị. Với tài liệu, chính trình tạo trang (MkDocs, Docusaurus, Hugo) có bản xem trước tự tải lại, hiển thị đúng style và điều hướng thật, tức là những gì người đọc sẽ thấy.

Để chỉnh sửa thay vì kiểm tra, một trình soạn thảo Markdown có khung xem trực tiếp — Obsidian, Typora, VS Code với tính năng xem trước tích hợp — tốt hơn việc lần nào cũng dán vào một trang, vì bản xem trước cập nhật khi bạn gõ và file vẫn nằm nguyên chỗ cũ. Trang này dành cho việc đọc Markdown của người khác, hoặc xem nhanh thứ gì đó bạn được gửi.