Bộ chuyển đổi HTML sang Markdown

Việc chuyển HTML sang Markdown thực sự làm gì

Một bộ chuyển HTML sang Markdown phân tích một đoạn HTML, đi qua cây DOM kết quả và phát ra cú pháp Markdown cho mỗi phần tử nó nhận diện. <h1> trở thành #; <strong> trở thành **đậm**; <a href="..."> trở thành [văn bản](url); <ul><li> trở thành danh sách dấu chấm. Công cụ chạy hoàn toàn trong trình duyệt qua JavaScript: dán HTML bên trái, bấm Chuyển sang Markdown, và đầu ra đã định dạng hiện ra bên phải. Không upload, không đi-về server, không telemetry, hãy kiểm chứng trong tab Network của DevTools khi bấm Chuyển, hoặc đặt trang offline (chế độ máy bay) sau khi đã tải xong và bộ chuyển vẫn hoạt động. Triển khai này dùng DOMParser tích hợp của trình duyệt để đọc HTML, rồi một bộ duyệt đệ quy nhỏ phát ra Markdown cho mỗi nút. Đây là bộ chuyển khoảng 150 dòng viết tay chứ không phải wrapper quanh Turndown, nghĩa là nó bao trọn trường hợp thông thường nhưng không bằng độ cấu hình đầy đủ của Turndown.

Khi nào bạn thực sự cần chuyển đổi này

Chiều ngược lại (Markdown sang HTML) được biết nhiều hơn, mọi trình sinh site tĩnh và mọi công cụ viết đều làm điều đó. Chiều xuôi (HTML sang Markdown) ít rõ hơn nhưng ngày càng phổ biến vì hệ sinh thái công cụ viết đã phân cực: HTML là định dạng nền của web (mọi CMS, nền tảng newsletter, mẫu CRM, site tĩnh cũ đều phát hoặc lưu HTML); Markdown là định dạng bản địa của mọi quy trình tài liệu, ghi chú và nội dung dưới quản lý phiên bản hiện đại nổi lên từ khoảng 2014. Bốn quy trình thực tế tạo nhu cầu chuyển đổi này.

• Cắt bài viết cho ứng dụng ghi chú. Lưu một bài web vào Obsidian, Notion, Logseq hoặc Roam, tất cả lưu ghi chú ở định dạng Markdown. Web Clipper chính thức của Obsidian (ra 2024) và extension trình duyệt phổ biến MarkDownload theo lược đồ này: trích DOM bài viết bằng thư viện Readability của Mozilla, chuyển sang Markdown, lưu vào đĩa. Khi bạn không thể truy cập HTML bên dưới qua extension (nội dung sau paywall, trình đọc nhúng, nội dung nhận qua email), hãy sao văn bản đã render, dán HTML kết quả vào bộ chuyển, lưu Markdown.
• Di trú từ CMS sang SSG ưu-tiên-Markdown. Chuyển tài liệu từ WordPress, Confluence, Drupal, Mediawiki hay Movable Type sang MkDocs (Tom Christie, Python), Docusaurus (Meta, React), Hugo (Steve Francia, Go), Jekyll (Tom Preston-Werner, Ruby, vẫn là engine sau GitHub Pages), Eleventy (Zach Leatherman, Node), VitePress (Evan You, Vue), hoặc Sphinx-with-MyST. Tất cả đều bản địa Markdown; nội dung CMS hiện hữu phải được xuất ra HTML và chuyển đổi hàng loạt.
• Đầu ra trình soạn WYSIWYG sang Markdown khả chuyển. Một biên tập dùng Google Docs, Word, Apple Notes, Evernote hay trình soạn rich-text của một CMS và payload clipboard là HTML. Họ muốn Markdown sạch để commit vào Git, dán vào trình soạn Markdown, gửi cho lập trình viên hay đưa vào site docs. Tính năng "Save as Web Page" của Microsoft Word tạo HTML nổi tiếng đậm đặc, đầy namespace XML, CSS có tiền tố mso-, thẻ riêng cho Office, và một bộ chuyển bỏ qua mọi thứ nó không hiểu và phát ra Markdown sạch chính là công cụ dọn đúng.
• Nội dung email để lưu trữ. Các nền tảng newsletter (Substack, Kit/ConvertKit, Beehiiv, Mailchimp) đều gửi HTML đã định dạng. Một độc giả lưu tham khảo ở Markdown có thể xem nguồn của thân email, dán HTML vào bộ chuyển và xếp kết quả vào ghi chú.

Triển khai tham chiếu: Turndown và họ hàng

Turndown (Dom Christie) là thư viện JavaScript HTML sang Markdown thống trị, khởi đầu dưới tên to-markdown năm 2012, đổi thành Turndown năm 2017 để phân biệt với fork, và phát hành dưới tên turndown trên npm với giấy phép MIT. Thiết kế dựa trên quy tắc: mỗi quy tắc có filter (các nút DOM nó áp dụng) và replacement (hàm tạo Markdown). Constructor nhận tùy chọn cho kiểu tiêu đề (atx # vs setext ===), đánh dấu chấm (-, + hoặc *), kiểu code block (thụt lề vs fence), phân cách emphasis (* vs _), phân cách bold (** vs __), kiểu link (inline vs reference), vân vân. Bảng, gạch ngang, mục danh sách check và autolink sống trong gói riêng turndown-plugin-gfm. markdownify (Matthew Tretter) là tương đương Python, được dùng rộng rãi trong pipeline scrape, chuyển notebook Jupyter, loader tài liệu LangChain và chuẩn bị bộ dữ liệu cho LLM. html2text (gốc của Aaron Swartz, người cũng cộng tác với John Gruber về thiết kế Markdown gốc năm 2004) là tùy chọn Python cũ hơn, vẫn dùng trong pipeline email lịch sử nhưng phần lớn đã bị thay thế. html-to-markdown (Johannes Kaufmann) là port Go của Turndown phổ biến cho binary scrape độc lập. Pandoc (John MacFarlane, người chủ trì dự án CommonMark) là bộ chuyển tài liệu phổ quát, xử lý bảng có ô gộp qua grid table, toán, trích dẫn, footnote, danh sách định nghĩa, và chuyển giữa hàng chục định dạng. Pandoc là công cụ HTML sang Markdown đầy đủ nhất hiện có, nhưng là binary Haskell hơn 60 MB phải được cài; nó không chạy trong trình duyệt.

Đánh đổi cơ bản: HTML giàu hơn Markdown

Mọi chuyển đổi HTML sang Markdown đều tất yếu mất mát vì định dạng nguồn diễn đạt những thứ định dạng đích không biết nói. Style inline (<span style="color:red">) không có ngữ pháp Markdown, từ vựng emphasis của Markdown giới hạn nghiêm ngặt ở đậm/nghiêng/gạch-ngang/code, không có cú pháp cho màu, font hay cỡ tùy ý. Class CSS (<div class="alert">) có nghĩa với một stylesheet nhưng không có với Markdown. Thuộc tính data tùy biến (data-track-event="...") là phần của hợp đồng JavaScript của trang, không phải tài liệu. Bảng có ô gộp (colspan, rowspan) không thể diễn đạt trong pipe table GFM. Media nhúng (<video>, <audio>, <iframe>) và điều khiển biểu mẫu không có tương đương Markdown. Khối gập <details><summary>, <figure><figcaption>, chú thích phát âm <ruby> cho CJK, microdata và microformat, không cái nào sống sót qua chuyển đổi. Cho mỗi cấu trúc không hỗ trợ, tác giả bộ chuyển chọn một trong ba chiến lược: dịch sang xấp xỉ Markdown làm mất thông tin, để qua ở dạng HTML thô nhúng trong Markdown (Markdown cho phép theo đặc tả; CommonMark mục 4.6 và 6.6 bao trùm điều này), hoặc bỏ hẳn. Triển khai này chọn "dịch nơi đối ứng rõ, ngược lại bọc trong suốt (render con, gỡ thẻ)", một mặc định dự đoán được và dễ suy luận, xử lý trường hợp thông thường ở giá khả năng cấu hình nâng cao.

Đối ứng kinh điển

• Tiêu đề: <h1>-<h6> tương ứng # đến ###### (kiểu atx). Dạng setext cũ hơn (gạch dưới bằng === và ---) cũng hợp lệ cho h1 và h2 nhưng ít dùng năm 2026.
• Đoạn văn: <p> trở thành văn bản thuần bao quanh bằng dòng trống. Một ngắt đoạn trong Markdown là một hoặc nhiều dòng trống.
• Emphasis: <strong> và <b> trở thành **đậm**. <em> và <i> trở thành *nghiêng*. <del> và <s> trở thành ~~gạch ngang~~ (mở rộng GFM; không trong CommonMark thuần).
• Liên kết: <a href="url">văn bản</a> trở thành [văn bản](url). Dạng reference-link ([văn bản][1] với [1]: url ở dưới) cũng là Markdown hợp lệ.
• Ảnh: <img src="url" alt="văn bản"> trở thành ![văn bản](url). Dấu chấm than phân biệt ảnh với liên kết.
• Code: <code> trở thành span backtick inline. <pre><code> trở thành block fence ba backtick. Triển khai này xử lý đúng yêu cầu CommonMark là span code inline dùng fence dài hơn khi nội dung chứa backtick (theo quy tắc đặc tả §6.1 của CommonMark).
• Danh sách: <ul> trở thành dòng dấu chấm -; <ol> trở thành dòng đánh số 1., 2., ... CommonMark chấp nhận số khởi đầu bất kỳ; renderer chuẩn hóa.
• Trích dẫn: <blockquote> tiền tố mỗi dòng con bằng >.
• Đường ngang: <hr> trở thành --- trên dòng riêng. *** và ___ cũng hợp lệ.
• Xuống dòng: <br> trở thành ngắt dòng. CommonMark cũng chấp nhận hai khoảng trắng cuối dòng hoặc backslash cuối dòng.
• Bảng: <table> trở thành pipe table GFM, hàng tiêu đề, hàng phân cách ---, hàng thân. Mở rộng GFM; không trong cốt CommonMark.

Phạm vi trung thực: công cụ này làm gì và không làm gì

Ba giới hạn trung thực cần biết. (1) Style inline và class CSS bị bỏ. Một <span style="color:red"> trở thành văn bản không style; một <p class="lede"> mất class. Không có ngữ pháp Markdown cho style inline tùy ý. (2) Bảng có ô gộp bị làm phẳng. Pipe table GFM không có cú pháp cho colspan hay rowspan; thông tin gộp âm thầm bị mất. Cho bảng phức tạp, hãy giữ nguồn ở HTML bên trong Markdown (CommonMark cho phép HTML nhúng) hoặc dùng Pandoc với đầu ra grid table. (3) Block code ra không có chỉ định ngôn ngữ. Nếu HTML của bạn chứa <pre><code class="language-js">, thuộc tính ngôn ngữ hiện bị bỏ, đầu ra là block fence không có ngôn ngữ. Bạn có thể thêm thủ công định danh ngôn ngữ sau backtick mở nếu renderer đích hỗ trợ tô màu cú pháp. Cảnh báo rộng hơn: nếu bạn dán HTML đầy đủ một trang web (từ "View Source"), nội dung <script> và <style> sẽ được phát ra như văn bản thô, gần như chắc chắn không phải điều bạn muốn. Cách giải: chỉ dán nội dung bài viết, hoặc sao từ view đã render (tự động cắt bỏ script và style), hoặc dọn HTML bằng DOMPurify hay tương tự trước khi chuyển đổi.

Tình hình Markdown năm 2026

Markdown đã 22 tuổi năm 2026. John Gruber công bố script Perl gốc năm 2004, với Aaron Swartz là cộng tác viên thiết kế. Bảng cố ý bị bỏ khỏi bản gốc của Gruber; cú pháp pipe table mà phần lớn độc giả ngày nay quen thuộc đến từ các phương ngữ sau, nổi bật nhất là GitHub Flavored Markdown. CommonMark, nỗ lực đặc tả nghiêm ngặt do Jeff Atwood và John MacFarlane tổ chức năm 2014, nay ở phiên bản 0.31.2 (28 tháng 1 năm 2024) và là phương ngữ phần lớn parser hiện đại nhắm. GitHub Flavored Markdown (GFM, chính thức hóa phiên bản 0.29-gfm ngày 6 tháng 4 năm 2019) là siêu tập của GFM thêm bảng, danh sách công việc, gạch ngang, autolink và quy tắc cấm HTML thô. GFM là phương ngữ phần lớn người dùng thực sự thấy trên web nhờ quy mô của GitHub. Markdown nay là định dạng bản địa của gần như mọi hệ sinh thái tài liệu cho lập trình viên; HTML vẫn là định dạng đầu ra phổ quát của web; chuyển đổi giữa hai cái phổ biến đúng bằng chiều ngược lại, và tồn tại cho khoảnh khắc bạn cần khẩn cấp, trong trình duyệt, không cài đặt và không dữ liệu rời thiết bị của bạn.

Quyền riêng tư: vì sao chỉ-trong-trình-duyệt quan trọng ở đây

HTML được dán vào bộ chuyển thường chứa dấu vết của nguồn gốc, markup nội bộ CMS, nội dung nháp chưa công bố, dữ liệu khách trong mẫu email, URL liên kết tiết lộ cấu trúc nội bộ site, tham chiếu ảnh trỏ đến server asset riêng. Bộ chuyển phía server upload tất cả những thứ đó đến dịch vụ bên thứ ba. Công cụ này chạy hoàn toàn trong trình duyệt qua JavaScript: HTML bạn dán không bao giờ đi qua mạng, hãy kiểm chứng trong tab Network của DevTools khi bấm Chuyển, hoặc đặt trang offline (chế độ máy bay) sau khi đã tải xong và bộ chuyển vẫn hoạt động. An toàn cho bản nháp chưa công bố, mẫu email khách, đoạn tài liệu nội bộ, hoặc bất kỳ HTML nào bạn không muốn bị sao vào ổ cứng của người lạ.

Câu hỏi thường gặp

Có hoạt động với tệp lớn không?

Có, vì việc chuyển đổi chạy trong trình duyệt, mức trần thực tế là bộ nhớ khả dụng của thiết bị bạn. Hàng chục nghìn dòng chuyển đổi trong dưới một giây trên một laptop hiện đại. Đầu vào rất lớn (hàng triệu nút) có thể đứng tab một thoáng khi đệ quy duyệt DOM. Cho chuyển đổi theo lô của xuất CMS đầy đủ, một script dùng Turndown trên Node hoặc markdownify trên Python là công cụ tốt nhất.

Style inline và class CSS sẽ ra sao?

Chúng bị bỏ hoàn toàn. Ngữ pháp emphasis của Markdown bao trùm đậm, nghiêng, gạch ngang và code; không có cú pháp cho màu, font, cỡ tùy ý hoặc style do class điều khiển. Nếu style thị giác quan trọng trong đầu ra của bạn, hãy giữ gốc ở HTML hoặc dùng định dạng đích giàu hơn như AsciiDoc, reStructuredText hay MDX (Markdown cộng thành phần JSX, được Docusaurus dùng). Cho các trường hợp lưu trữ bài viết và di trú CMS mà công cụ này được dựng cho, bỏ style là hành vi đúng, ý nghĩa của Markdown chính là gỡ nhiễu thị giác và chỉ giữ cấu trúc.

Công cụ này có hoạt động offline không?

Có, một khi trang đã tải, việc chuyển đổi chạy hoàn toàn trong JavaScript trong trình duyệt. Không có cuộc gọi mạng nào trong khi chuyển đổi. Hãy kiểm chứng trong tab Network của DevTools khi bấm Chuyển, hoặc đặt thiết bị offline (chế độ máy bay) sau khi trang đã tải và công cụ vẫn hoạt động.

Đây có phải Turndown không?

Không. Turndown (thư viện của Dom Christie) là triển khai tham chiếu trong JavaScript và là công cụ tự nhiên để chọn trong dự án Node, nhưng đó là một phụ thuộc đáng kể với khả năng cấu hình đầy đủ cho kiểu tiêu đề, đánh dấu chấm, kiểu link, kiểu code block, vân vân. Công cụ trong-trình-duyệt này là việc duyệt DOM viết tay nhỏ hơn, khoảng 150 dòng, nhắm trường hợp thông thường (tiêu đề, đoạn văn, emphasis, link, ảnh, danh sách, trích dẫn, code fence, bảng cơ bản) không có bề mặt cấu hình. Cho các luồng mà site này được dựng cho (chuyển đổi lẻ trong trình duyệt, không cài đặt), triển khai nhỏ hơn là dạng đúng; cho pipeline scrape production cần quy tắc cấu hình được, Turndown vẫn là lựa chọn đúng.

Bảng được xử lý thế nào?

Thành pipe table GFM: một hàng tiêu đề, một hàng phân cách dấu gạch, và một hàng thân mỗi <tr>. Pipe table phẳng, chúng không thể biểu diễn colspan, rowspan, nội dung ô nhiều dòng, danh sách trong ô, hay căn lề từng ô. Nếu bảng HTML của bạn dùng một trong các tính năng đó, bộ chuyển này tạo ra pipe table suy biến mất cấu trúc bổ sung. Cho bảng phức tạp, hai tùy chọn thực tế: (a) giữ bảng ở HTML thô bên trong Markdown, CommonMark cho phép HTML nhúng, và tin renderer đích để nó qua; (b) dùng Pandoc với đầu ra grid table, có thể diễn đạt ô gộp.

Tôi có thể dán HTML đầy đủ của một trang web không?

Bạn có thể, nhưng có lẽ bạn không nên. Nguồn đầy đủ của một trang web hiện đại chứa thẻ <script> với mã JavaScript, block <style> với CSS, pixel theo dõi, markup quảng cáo và bình luận mẫu CMS. Bộ chuyển này không cắt rõ nội dung script và style, nên tất cả những thứ đó kết thúc thành văn bản thô trong đầu ra Markdown. Cách tiếp cận sạch: chỉ chọn phần tử bài viết trong DevTools (chuột phải vào bài viết, "Inspect", rồi chuột phải nút tương ứng trong panel Elements và "Copy outerHTML"), hoặc dùng bước trích nội dung (thư viện Readability của Mozilla, hoặc dạng đóng gói trong Reader Mode của Firefox) trước khi dán. Cho luồng dựa trên extension trình duyệt hỗ trợ bước trích tự động, hãy xem Obsidian Web Clipper hoặc MarkDownload.

Công cụ liên quan