Markdown sang HTML: quy trình xuất bản sạch

Pipeline xuất bản cần định dạng master sống sót qua công cụ, host và đợt thiết kế lại. Markdown văn bản thuần là master đó: đọc được trong mọi trình soạn thảo, diff được trong version control, và độc lập với bất kỳ mẫu HTML nào render nó năm nay.

Kỷ luật làm nó hoạt động là luồng một chiều: Markdown do tay chỉnh, HTML do trình chuyển đổi sinh, và không ai vá đầu ra thủ công. Ngay khoảnh khắc HTML đã xuất bị sửa tay, có hai master, và chúng sẽ trôi xa nhau.

• Khả chuyểnKhả chuyển: tệp Markdown mở trong mọi trình soạn thảo và chuyển sang HTML, PDF, slide hay hệ thống tài liệu mà không cần dự án di trú.
• Diff đượcKhả năng review: thay đổi văn xuôi hiện thành diff dòng sạch, trong khi master HTML chôn chỉnh một từ trong thẻ và thuộc tính.
• Cấu trúc, không phải kiểuTách mối quan tâm: nguồn mang cấu trúc — tiêu đề, danh sách, trích dẫn — trong khi theme quyết định typography, nên thiết kế lại không bao giờ chạm kho lưu trữ.

Trình chuyển đổi có chủ đích hỗ trợ một tập con cố ý, vì mỗi cấu trúc được hỗ trợ là thêm một cách lẩn markup chẳng ai review. Biết nội dung của bạn nằm đâu so với ranh giới đó trước khi dựa vào việc chuyển đổi.

Ở chế độ Markdown sang HTML, cú pháp ảnh chỉ giữ văn bản thay thế, không giữ ảnh hay URL; HTML thô được escape thành văn bản. Ở chế độ HTML sang Markdown, bảng dán vào trở thành khối văn bản có hàng rào và mất lưới. Kiểm tra kết quả trước khi xuất bản.

• Chuyển đổi sạchChuyển đổi sạch: tiêu đề tới sáu cấp, đoạn văn, đậm, nghiêng, gạch ngang, code nội dòng, khối code rào, danh sách có thứ tự và không thứ tự, trích dẫn khối, đường kẻ ngang, và liên kết nội dòng.
• Mất mát đã biếtNgoài tập tính năng hỗ trợ, kết quả tùy chiều chuyển đổi: ảnh Markdown chỉ giữ văn bản thay thế, HTML thô trong Markdown được escape thành văn bản, còn bảng HTML thành khối văn bản có hàng rào khi chuyển về Markdown. Hãy xem đầu ra của chú thích và danh sách tác vụ thay vì mặc định chúng còn nguyên.
• Test bài thậtBài test đơn giản: chuyển một bài viết đại diện và đọc đầu ra. Thứ gì thiếu trong kết quả chưa từng nằm trong hợp đồng.

HTML đã chuyển đổi có thể được chèn vào trang, nên công cụ mặc định làm sạch nó. Phần tử hoạt động bị loại, thẻ không biết được tháo vỏ, còn thuộc tính bị xóa trừ URL liên kết được phép và giá trị start hợp lệ của danh sách có thứ tự.

Khung xem trước render đầu ra đã sanitize và không bao giờ tải tài nguyên từ xa, nên kể cả dán markup thù địch cũng không thể khiến chính công cụ gọi về nhà.

• Nội dung chủ động bị gỡPhần tử mang hành vi chủ động — script, style, iframe, object, embed, svg, form, video, audio, img — bị gỡ cùng nội dung, không chỉ bị vô hiệu.
• Thuộc tính bị tướcKiểu inline, trình xử lý sự kiện và class từ nguồn đều bị xóa. Liên kết an toàn giữ href; danh sách có thứ tự hợp lệ giữ start.
• Được báo, không âm thầmKhông gian làm việc báo thứ nó đã gỡ — số nút bị bỏ và thuộc tính bị tước — nên sanitization là sự kiện nhìn thấy, không phải biến đổi âm thầm.

Tài liệu đã render phần lớn là liên kết, và liên kết là nơi sanitization trở nên cụ thể. Trình chuyển đổi chấp nhận URL http, https và mailto cùng #fragment trong trang; mọi thứ khác — javascript:, data:, chiêu protocol-relative — mất href và render thành văn bản thuần.

Đối chiếu allowlist với nội dung của bạn trước khi chuẩn hóa trên một trình chuyển đổi: bộ tài liệu hợp pháp liên kết tới mirror ftp hay scheme ứng dụng tùy biến cần giữ các liên kết đó bằng tay, vì chẳng sanitizer lành mạnh nào tự động cho chúng qua.

• Allowlist schemeLiên kết sống sót được đóng dấu rel="noreferrer noopener", nên liên kết được theo không thể nhìn hay script trang đã mở nó.
• noopener noreferrerCùng quy tắc áp dụng cả hai chiều: liên kết viết bằng Markdown được kiểm tra khi chuyển đổi, và href tìm thấy trong HTML dán vào được kiểm tra lại sau sanitization.
• Nhãn sống sótKhi liên kết mất scheme, văn bản nhãn vẫn ở lại — điều hướng hỏng hiện rõ ngay thay vì phát hành payload javascript: âm thầm.

Chuyển HTML về Markdown là trích lại nội dung, không phải khôi phục nguyên vẹn. Tiêu đề, đoạn văn, nhấn mạnh, danh sách, trích dẫn và mã được hỗ trợ sẽ trở lại Markdown. Cấu trúc khác có thể bị đơn giản hóa hoặc loại bỏ khi làm sạch và chuyển đổi.

Coi HTML-sang-Markdown là cách rút văn xuôi ra khỏi trang bạn không còn kiểm soát — bản xuất CMS cũ, tài liệu chỉ tồn tại dạng HTML đã render. Rồi sửa thứ vòng quay không thể: thêm lại ảnh, dựng lại bảng, và từ đó giữ Markdown làm master.

• Bảng sụp đổBảng mất lưới và trở thành khối văn bản có hàng rào; dữ liệu dạng bảng cần được biên soạn lại hoặc xuất CSV.
• Media bị gỡẢnh, video và nhúng tương tác biến mất theo thiết kế — sanitizer đã gỡ chúng như nội dung chủ động trước khi Markdown được dựng.
• Chữ sống lâu hơn kiểuĐịnh dạng ngoài tập con — span, div, class, đích anchor — không để lại dấu vết; chữ sống sót, trình bày thì không.

Bước chuyển đổi chạy lúc xuất bản, một lần mỗi bài: soạn và review bằng Markdown, chuyển sang HTML đã sanitize, xác minh kết quả render, và phát hành. Mọi thứ diễn ra trong tab trình duyệt — bản nháp không bao giờ tải lên, điều quan trọng khi nội dung là đợt ra mắt chưa công bố.

• Bước lúc xuất bảnKhông gian làm việc nhận tối đa 256 KiB nguồn và sinh tối đa 512 KiB đầu ra — thoải mái cỡ chương sách — và báo lỗi rõ ràng qua giới hạn đó thay vì cắt cụt âm thầm.
• Giới hạn rõ ràngSao chép đầu ra vào trường CMS hoặc tải xuống thành tệp; cả hai đường đều lấy cùng tài liệu đã sanitize mà bản xem trước đã cho bạn thấy.
• Chuyển lại, đừng váGiữ Markdown trong version control cạnh mã nó tài liệu hóa, và chuyển lại sau mỗi lần chỉnh thay vì vá HTML cũ.