html2text

html2text is a Rust crate that converts HTML into plain text (a Rust String) or text spans carrying annotations such as colours and hyperlinks. It builds on the Servo project’s html5ever parser, walking the DOM to produce readable, width-aware output suitable for terminals, console viewers, and the text/plain fallback of HTML emails.

Beyond the simple one-call from_read() helper, it exposes a layered configuration API and pluggable text decorators, plus optional CSS and colour support behind feature flags, so you can go from a quick conversion to fine-grained control over how rich HTML collapses into text.

What You Get

• A one-call from_read(input, width) API that converts HTML to width-wrapped plain text
• A layered config builder plus rich variants (from_read_rich, from_read_coloured) for annotated and coloured output
• Pluggable TextDecorator implementations (Plain, Rich, Trivial) to control how elements map to text
• Optional CSS handling and terminal colour/styling behind Cargo feature flags
• Optional XHTML/XML parsing mode for documents that must not be parsed as HTML

Common Use Cases

• Generating the text/plain fallback body for HTML emails
• Displaying HTML content inside a terminal or TUI application
• Extracting readable plain text from web pages for indexing or previews
• Rendering coloured, hyperlink-aware HTML in the console with termion or similar

Under The Hood

Architecture - The pipeline flows from HTML bytes through Servo’s html5ever parser into a DOM (via the bundled markup5ever_rcdom), which is walked in src/lib.rs to build an intermediate render tree; a Renderer trait in src/render/mod.rs then turns that tree into output, with TextRenderer/SubRenderer in src/render/text_renderer.rs maintaining a stack of sub-renderers to handle nested blocks, tables, and width-constrained wrapping, propagating a TooNarrow result when a column cannot fit. Output formatting is delegated to pluggable TextDecorator implementations (Plain, Rich, Trivial) so the same tree can become plain text, annotated spans, or coloured terminal output.

Tech Stack - Written in Rust (edition 2024, rust-version 1.85), it depends on html5ever 0.39 and tendril for parsing, unicode-width for correct display-width wrapping, and thiserror 2.0 for typed errors. Optional capabilities sit behind Cargo features: css pulls in nom 8 for a small CSS parser (src/css.rs, src/css/parser.rs), xml adds xml5ever for XHTML mode, and html_trace/html_trace_bt wire in log and backtrace for verbose diagnostics. A separate workspace member, html2text-cli, provides the installable command-line wrapper.

Code Quality - The crate is well tested, with roughly 172 #[test] functions concentrated in a large src/tests.rs (about 3,700 lines) plus dedicated CSS parser tests, exercising rendering across many HTML constructs. Errors are modelled explicitly with thiserror and threaded through Result types (including the internal TooNarrow signal) rather than panicking in the library entry points, and the render code uses clear trait boundaries and typed decorators. A benches directory covers table rendering performance.

API Design - The public surface is deliberately layered: from_read(input, width) is a single-call path for the common case, while config::plain() and friends offer a builder for finer control, and from_read_rich/from_read_coloured expose annotations for styled output. Naming is consistent and discoverable, documentation is published on docs.rs with runnable README examples and two example programs (html2text, html2term), so getting started requires very little boilerplate while advanced CSS and colour features remain opt-in.