pip install pyhtml2text

from pyhtml2text import html2markdown

html = """<h2>Before you start</h2>
<p>Read the <a href="setup.html">setup guide</a> and <b>back up</b> your data.</p>
<img src="https://jared.lynskey.co.nz/img/diagram.png" alt="How it fits together">
<table><tr><th>Plan</th><th>Price</th></tr><tr><td>Basic</td><td>Free</td></tr></table>"""

print(html2markdown(html, base_url="https://example.com/docs/intro.html"))

## Before you start

Read the [setup guide](https://example.com/docs/setup.html) and **back up** your data.

![How it fits together](https://example.com/img/diagram.png)

| Plan | Price |
| --- | --- |
| Basic | Free |

Mọi chuyện bắt đầu từ một pull request gửi cho rust-html2text. Người bảo trì (maintainer) đã đóng nó vì nó được viết bằng LLM, nên pyhtml2text chạy trên một bản fork. Bài này kể chuyện đó diễn ra thế nào, bản fork và gói Python có gì, và tôi đã kiểm tra thế nào để chắc rằng Markdown đầu ra là đúng.

Vì sao tôi cần nó

#

Ứng dụng chợ kiêm cộng đồng mà tôi đang làm trả về Markdown thay vì HTML khi nhận Accept: text/markdown, dành cho các AI agent và client LLM không muốn phải lội qua thanh điều hướng và chân trang. Phần xử lý ở tầng edge tôi đã viết trong bài về crawler và bộ nhớ đệm. Những trang lấy từ dữ liệu của ứng dụng thì HTML chỉ là một vỏ JavaScript rỗng, nên Markdown được dựng thẳng từ dữ liệu. Phần còn lại là HTML tĩnh (trang giới thiệu, điều khoản pháp lý và blog), và phần đó thì phải chuyển đổi.

Vấn đề khi chuyển đổi nằm ở các liên kết. Một trang web tĩnh đầy những liên kết kiểu /en/posts/... và ../setup/. Trong trình duyệt thì không sao, vì trình duyệt biết chúng đến từ trang nào. Một agent đọc Markdown thì không có ngữ cảnh đó, nên nó không thể đi theo /login. Nó cần https://example.com/login.

Thư viện html2text viết bằng Python thuần có tuỳ chọn baseurl cho việc này, và lúc đầu tôi dùng nó. Nhưng nó chậm, và Markdown của nó có vài vấn đề mà tôi sẽ nói ở phần dưới. rust-html2text thì nhanh và được kiểm thử kỹ, nhưng lại không có cách nào phân giải liên kết.

Hỏi dự án gốc trước

#

Ngày 29 tháng 8, tôi mở issue #287, mô tả trường hợp sử dụng và hành vi tôi muốn: phân giải theo RFC 3986, giữ nguyên các URL tuyệt đối và các liên kết mailto:, data: và #fragment. Vài phút sau, tôi mở pull request #288. Nó thêm tuỳ chọn Config::base_url(...), và trong issue tôi có nói rằng đây chỉ là điểm khởi đầu, và tôi sẽ hiểu nếu người bảo trì muốn làm theo cách khác.

Ngày 11 tháng 10, người bảo trì đóng PR:

Thanks for the contribution, but I’m unable to accept this as it appears to be LLM generated. (I have now added a brief policy to the README.md - it wasn’t previously stated)

(Tạm dịch: “Cảm ơn bạn đã đóng góp, nhưng tôi không thể nhận cái này vì có vẻ nó được tạo bằng LLM. (Tôi vừa thêm một chính sách ngắn vào README.md, trước đây chưa có.)”)

và trả lời trong issue:

Hi - this is a reasonable feature request, thanks! I have closed the PR as it appears to be LLM-written which I can’t accept, but thanks for the attempt.

A short HTML sample and expected output would definitely help get the feature implemented!

(Tạm dịch: “Chào bạn, đây là một yêu cầu tính năng hợp lý, cảm ơn! Tôi đã đóng PR vì có vẻ nó được viết bằng LLM, điều mà tôi không thể chấp nhận, nhưng cảm ơn bạn đã thử. Một mẫu HTML ngắn kèm đầu ra mong muốn chắc chắn sẽ giúp tính năng này được hiện thực!”)

README giờ có chính sách này:

At this time, this project is not able to accept code contributions produced with generative AI/LLMs due to the uncertain copyright status.

(Tạm dịch: “Hiện tại, dự án này không thể nhận các đóng góp mã được tạo bằng AI tạo sinh/LLM, vì tình trạng bản quyền còn chưa rõ ràng.”)

Nhận định đó là đúng: tôi viết đoạn mã ấy bằng một trợ lý lập trình AI. Tôi cũng không nghĩ chính sách đó vô lý. Tình trạng bản quyền của đầu ra từ LLM chưa ngã ngũ, và người gánh rủi ro khi gộp nó vào một crate MIT mà nhiều dự án khác phụ thuộc là người bảo trì. Đó là dự án của họ, và câu trả lời rất lịch sự. Yêu cầu tính năng đó đến giờ vẫn còn mở.

Dù vậy, tôi vẫn cần tính năng này, và tranh cãi với người bảo trì về chính sách đóng góp của chính dự án họ không phải là cách hay để có nó. Vì thế tôi giữ thay đổi trên một bản fork rồi xây gói Python dựa trên đó, và cả hai đều ghi rõ rằng chúng không phải là bản gốc (upstream).

Bản fork có gì

#

Bản fork là nhánh pyhtml2text-perf trong bản fork rust-html2text của tôi. Tôi chỉ giữ ba commit nhỏ để nó luôn rebase gọn gàng lên dự án gốc (upstream). Commit chính là tùy chọn Config::base_url lấy từ PR: liên kết tương đối được phân giải theo RFC 3986 §5.3, và nếu không truyền base URL thì đầu ra giữ nguyên. Commit thứ hai khiến crate không còn dựng lại các quy tắc style mỗi lần được gọi, nhờ vậy một đoạn HTML ngắn giảm từ 7.3 µs xuống 5.6 µs. Với trang lớn thì chẳng đáng là bao, nhưng gọi vài nghìn lần thì cộng dồn lại cũng đáng kể. Commit thứ ba chỉ mở ra (export) những phần mà bộ chuyển Markdown ở dưới cần dùng từ crate.

Gói Python

#

pyhtml2text được xây bằng PyO3 và maturin, và có hai hàm:

from pyhtml2text import html2text, html2markdown

html2text(html, width=80, *, base_url=None, decorate=True, link_footnotes=True,
          table_borders=True, wrap_links=True, max_wrap_width=None, raw=False)

html2markdown(html, *, base_url=None)

html2text là bộ render văn bản thuần của rust-html2text, vốn được làm cho terminal và phần text/plain của email:

print(html2text('<p>Please <a href="https://jared.lynskey.co.nz/login">sign in</a> first.</p>',
                base_url="https://example.com/docs/page.html"))

Please [sign in][1] first.

[1]: https://example.com/login

Vài điểm về phần binding có thể không hiển nhiên:

• Cả hai hàm đều nhận str hoặc bytes UTF-8, nên bạn có thể truyền thẳng response.content mà không cần giải mã trước. Dữ liệu đầu vào được mượn (borrow), không bị sao chép.
• GIL được nhả ra trong lúc chuyển đổi. Từ đầu tới cuối đều là Rust thuần, nên các luồng (thread) chạy song song được trên nhiều nhân. Module cũng khai báo rằng nó không cần GIL, nên Python 3.14t bản free-threaded sẽ không bật GIL trở lại khi import module.
• Một panic sẽ trả về dưới dạng ValueError. Mặc định PyO3 ném PanicException, thứ mà except Exception không bắt được. Một web worker tưởng rằng mình đã xử lý hết lỗi chuyển đổi sẽ sập vì nó, nên phần binding bắt panic lại và ném ra dưới dạng ValueError.
• Có 30 wheel: wheel abi3 cho CPython 3.10 trở lên, cộng thêm wheel cho bản free-threaded 3.14t, trên Linux (glibc và musl), macOS và Windows, ở mọi kiến trúc mà CI của maturin build được. Vì vậy không ai cần cài bộ công cụ Rust để cài gói này.

Làm cho nó nhanh

#

Bản 0.2.0 nhanh hơn 0.1.0 từ 1.5 đến 1.7 lần trên trang thật và nhanh gấp đôi với đoạn HTML ngắn, mà đầu ra vẫn giống hệt đến từng byte. Phần lớn là nhờ tối ưu hóa dựa trên profile (profile-guided optimisation, PGO): CI build một wheel có gắn đo đạc (instrumented), chạy nó qua một bộ dữ liệu huấn luyện gồm các trang tài liệu và RFC, rồi dùng profile thu được để build wheel thật. Kết quả là nhanh hơn khoảng 25% trên những trang không nằm trong bộ huấn luyện, và chỉ áp dụng trên các nền tảng mà CI chạy được bản build đo đạc một cách native. Phần còn lại đến từ việc chuyển sang bộ cấp phát bộ nhớ mimalloc, vốn xử lý hàng loạt lần cấp phát nhỏ tốt hơn hẳn, và từ thay đổi về quy tắc style trong bản fork.

Để chắc chắn việc tăng tốc không làm thay đổi gì, tôi băm (hash) đầu ra của một tập trang thật với mọi tổ hợp tùy chọn, kèm các trường hợp biên như đầu vào rỗng hay lồng nhau cực sâu. Mỗi thay đổi đều phải giữ nguyên toàn bộ giá trị băm.

Đây là thời gian trung vị trên một máy Mac Apple Silicon, khi chuyển sang Markdown:

Và khi chuyển sang văn bản thuần:

HTML lồng nhau rất sâu, và một bản vá cho html5ever

#

Chẳng ai tự tay viết 40,000 danh sách lồng vào nhau. Nhưng nếu bạn chuyển đổi những trang mà mình không viết ra, sớm muộn gì cũng sẽ có thứ độc hại hoặc bị hỏng gửi đến bạn một trang như thế. Với parser nguyên bản, 40,000 cặp <ul><li> lồng nhau mất 6 giây để phân tích, tức là một worker bị kẹt cứng chỉ vì một yêu cầu.

Nguyên nhân nằm ở html5ever, bộ phân tích HTML5 mà rust-html2text dùng. Phần lớn thẻ mở cấp khối (block-level) phải kiểm tra xem có phần tử <p> nào đang mở “trong button scope” hay không, và html5ever trả lời câu đó bằng cách duyệt toàn bộ ngăn xếp các phần tử đang mở. Lồng càng sâu thì mỗi thẻ càng tốn thời gian, nên tổng thời gian tăng theo bình phương độ sâu.

Gói này đi kèm html5ever 0.39.0 với đúng một bản vá: câu trả lời được cập nhật sẵn mỗi khi một phần tử được mở hoặc đóng, nên việc kiểm tra không còn phụ thuộc vào độ sâu nữa. Cùng tài liệu đó giờ chỉ mất 0.14 giây để phân tích. Để chắc bản vá không làm thay đổi gì khác, tôi so sánh DOM do bộ phân tích gốc và bản đã vá tạo ra trên toàn bộ bài kiểm thử dựng cây (tree-construction) của html5lib, khoảng 20 trang thật và 300,000 tài liệu tag soup ngẫu nhiên, và tất cả đều giống hệt nhau.

Vì cùng lý do đó, bộ chuyển Markdown cũng có giới hạn riêng. Không đầu vào nào có thể làm tràn ngăn xếp của luồng; blockquote và danh sách sẽ ngừng thụt lề khi vượt quá 32 cấp, để đầu ra không phình theo bình phương; và một bảng mà lưới sau khi trải ra vượt quá 100,000 ô sẽ chỉ được ghi ra nội dung các ô.

html2markdown

#

Phiên bản 0.3.0 thêm html2markdown, và phần lớn công sức trong gói này dồn vào nó. Bộ render của rust-html2text tạo ra văn bản trông giống Markdown, nhưng nó được ngắt dòng cho terminal và không được làm ra để phân tích lại. Vì vậy html2markdown chỉ mượn phần phân tích cú pháp, còn đầu ra thì tự ghi theo CommonMark, cộng thêm bảng pipe và ~~strikethrough~~ theo kiểu GitHub:

• Tiêu đề #, gạch đầu dòng -, _emphasis_ và **strong**.
• Liên kết và hình ảnh nội dòng (inline), được chuyển thành địa chỉ tuyệt đối khi có base_url. Một liên kết chỉ chứa mỗi biểu tượng (icon) sẽ dùng aria-label hoặc title của nó làm văn bản.
• Khối mã có rào (fenced code block), gắn tên ngôn ngữ khi trang có ghi (class="language-python").
• Bảng pipe. Ô trải nhiều hàng hoặc nhiều cột trở thành các ô trống, bảng không có hàng tiêu đề sẽ được thêm một hàng tiêu đề trống, và bảng dùng để dàn trang được ghi ra thành các đoạn văn.
• Không ngắt dòng. Nội dung ẩn (hidden, aria-hidden, display: none), script, style và các điều khiển biểu mẫu (form control) bị bỏ qua.

Chỉ escape những gì cần thiết

#

Một số bộ chuyển HTML sang Markdown escape mọi ký tự có thể là cú pháp Markdown. Ví dụ, markdownify mặc định escape mọi _ và *. Đầu ra vẫn đúng, nhưng đầy những snake\_case và 5 \* 3, khó đọc hơn với con người và tốn token vô ích với một mô hình. pyhtml2text chỉ escape một ký tự ở những chỗ mà nếu không escape, một parser CommonMark sẽ đọc nó thành cú pháp:

html2markdown('<p>Use <code>snake_case</code>, 5 * 3, $5 and '
              '<a href="../setup.html">setup</a></p>',
              base_url="https://example.com/docs/intro.html")

Use `snake_case`, 5 * 3, $5 and [setup](https://example.com/setup.html)

In đậm trước một tiểu từ tiếng Hàn

#

Vấn đề này đến từ chính các trang trong ứng dụng của tôi. Trong tiếng Hàn, tiểu từ ngữ pháp (particle, chẳng hạn 의 có nghĩa “của”) được viết dính liền ngay sau danh từ, không có dấu cách. Vì vậy một thuật ngữ in đậm có chứa dấu ngoặc trông như thế này:

<p><b>타이타닉(Titanic)</b>의 감독</p>

Cách viết Markdown hiển nhiên nhất là **타이타닉(Titanic)**의, cũng chính là thứ markdownify tạo ra, và nó không hoạt động. Quy tắc flanking của CommonMark không cho ** đóng lại ngay sau một dấu câu, trừ khi theo sau nó là dấu cách hoặc thêm một dấu câu nữa. Mà 의 là một chữ cái, nên các dấu sao bị giữ nguyên dưới dạng ký tự thường. html2text bản Python thuần né chuyện này bằng cách chèn thêm một dấu cách:

**타이타닉(Titanic)** 의 감독

Cách đó hiển thị được chữ in đậm, nhưng làm thay đổi tiếng Hàn. Tiểu từ giờ bị tách ra thành một từ riêng, mà trong tiếng Hàn thì đó là lỗi chính tả, giống như viết “của” tách khỏi một từ mà lẽ ra nó phải dính vào. pyhtml2text thay vào đó đưa dấu câu ra ngoài cặp dấu in đậm:

**타이타닉(Titanic**)의 감독

Dấu ngoặc đóng không còn được in đậm nữa, nhưng phần nhấn mạnh vẫn được phân tích đúng và mọi ký tự của bản gốc đều được giữ lại. Điều tương tự cũng áp dụng cho tiếng Nhật và tiếng Trung, và cho bất kỳ ngôn ngữ nào không đặt dấu cách trước phần đi theo sau.

Kiểm tra đầu ra bằng cách đọc ngược lại

#

Tôi không tin một bộ chuyển đổi chỉ vì nó qua hết bài kiểm thử đơn vị (unit test), bởi lỗi trong đầu ra Markdown thường nằm ở những tổ hợp mà chẳng ai nghĩ tới để viết kiểm thử. Vì vậy đầu ra được kiểm tra bằng cách đọc ngược lại.

Trong lúc chuyển đổi, mỗi đoạn văn được phân tích lại theo CommonMark để xác nhận phần nhấn mạnh được đọc đúng như ý. Nếu không đúng, đoạn đó được viết lại bằng kiểu nhấn mạnh còn lại (* thay cho _, hoặc ngược lại); nếu cả hai đều không được thì giữ lại chữ, liên kết và mã, chỉ bỏ định dạng, để không mất chữ nào. Bộ kiểm thử thì chạy một vòng khứ hồi (round trip) qua một bộ phân tích Markdown khác, rồi so từng chữ hiển thị, đích liên kết và nguồn ảnh với HTML gốc. Chữ bị cú pháp chưa escape “nuốt” mất, liên kết không phân tích được hay một dấu * lạc chỗ đều hiện ra thành chỗ khác biệt. Nó chạy trên các trang thật và hàng chục nghìn tài liệu ngẫu nhiên, và khi có lỗi thì thu nhỏ tài liệu đó về một trường hợp tối giản.

Chạy thật

#

Phần thương lượng markdown (markdown negotiation) trong ứng dụng của tôi chuyển từ html2text bản Python thuần sang pyhtml2text ngay trong ngày 0.3.0 ra mắt. Trên một trang hướng dẫn, thời gian chuyển đổi giảm từ 4.2 ms xuống 0.36 ms, nhanh hơn khoảng 12 lần. Liên kết đều là tuyệt đối, bảng là bảng pipe thật sự, còn chữ in đậm tiếng Hàn vẫn giữ tiểu từ dính liền. Các wheel abi3 vốn đã hỗ trợ Python 3.14 trên x86_64 và arm64, nên container image không cần cài thêm gì để dùng nó.

Ghi công, và nơi báo lỗi

#

Phần render văn bản thuần là rust-html2text của Chris Emerson, theo giấy phép MIT. pyhtml2text bổ sung một bản fork của nó, một bản html5ever đã vá (MIT/Apache-2.0) và bộ chuyển đổi Markdown. Gói này không liên kết với cũng như không được bảo trợ bởi dự án nào trong hai dự án đó, nên vui lòng báo lỗi tại trang issue của pyhtml2text, đừng báo lên dự án gốc. Lỗi nào trong mã này thì tôi là người phải sửa, và những người bảo trì dự án gốc không nên phải nhận báo cáo về đoạn mã mà họ đã từ chối nhận.

Nếu bạn đang chuyển đổi HTML bằng Python, nhất là để cho một mô hình đọc, hãy thử nó:

pip install pyhtml2text

Mã nguồn có trên GitHub, và changelog liệt kê mọi thay đổi từ 0.1.0 đến 0.3.0.