html2text Rust Crate

When the css feature is enabled, html2text can handle basic CSS selectors and colors.

Style Sources

Style rules are sourced from:

• Document <style> elements
• Inline style attributes
• <font color=...> tags
• Custom rules added via Config::add_css(...) (available regardless of use_doc_css() setting).

Accessing Colors

To utilize CSS colors in your output, you have two options:

1. Rich Annotations: Use from_read_rich() or its variants. This returns a tree containing Colour(..) annotations.
2. Direct Coloring: Use from_read_coloured(). This function accepts a closure that allows you to map RichAnnotations directly to terminal styling (e.g., using termion).

// Example concept: using from_read_rich to get annotations
// let rich_text = from_read_rich(&html[..], 80);
// // rich_text will contain nodes like Colour(..)

You can generate enhanced terminal output using specific flags. Note that syntax highlighting requires the css_ext Cargo feature to be enabled in the underlying library.

Available advanced options:

• --colour: Enables ANSI colors in the output.
• --css: Enables CSS rule processing.
• --syntax: Enables syntax highlighting using syntect.
• --agent-css '<selector> { <rule>; }': Allows passing custom CSS rules to the agent.

html2text --colour --css --syntax --agent-css 'pre.rust { x-syntax: rs; }' < file_with_rust_code.html

The html2text command-line tool converts HTML into text formats. By default, it produces text with ASCII annotations (similar to Markdown) for elements like <strong> and lists, and includes table formatting. It reads from standard input and writes to standard output by default.

html2text foo.html

To install the command-line interface wrapper for html2text, use cargo install:

cargo install html2text-cli

By default, html2text parses documents as HTML. If the xml feature is enabled, the parser will automatically switch to XHTML mode if the document begins with an <?xml?> declaration.

You can manually control this behavior using Config::xml_mode().

The TextDecorator trait uses an associated type Annotation to allow renderers to pass metadata to the final output stage.

1. When a decorator method like decorate_em_start is called, it returns a (String, Self::Annotation) tuple. The String is the literal text decoration (e.g., *), and the Annotation is the metadata.
2. This Annotation is then attached to the TaggedString via the TaggedLineElement structure.
3. A consumer of the rendered TaggedLine<Annotation> can iterate through the elements and use the Annotation to apply environment-specific styling (like ANSI escape codes for terminal colors) to the corresponding text spans.

The conversion process follows a two-phase pipeline:

1. Tree Construction: HTML is parsed into a RenderNode tree. During this phase, styles are computed and elements are categorized into RenderNodeInfo variants.
2. Rendering: The render_tree_to_string function processes the tree in two sub-steps:
   • Phase 1 (Size Estimation): A tree_map_reduce pass calculates size estimates (like min_width and prefix_size) for nodes to ensure proper layout (especially for tables and lists).
   • Phase 2 (Actual Rendering): A TextRenderer traverses the tree. It uses a TextDecorator to handle text styling and manages a stack of SubRenderer instances to handle indentation and nested structures (like blockquotes or list items).

The NodeData enum defines the specific type of information stored in a Node. When processing the DOM, you will typically match on these variants:

• Document: The root node.
• Doctype: Contains name, public_id, and system_id (as StrTendril).
• Text: Contains the text content in a RefCell<StrTendril>.
• Comment: Contains the comment text as a StrTendril.
• Element: Contains the name (QualName), attrs (RefCell<Vec<Attribute>>), template_contents (RefCell<Option<Handle>>), and mathml_annotation_xml_integration_point (bool).
• ProcessingInstruction: Contains a target and contents (both StrTendril).

The library converts HTML elements into a tree of RenderNode objects. Each HTML tag is mapped to a specific RenderNodeInfo variant which dictates how it will be rendered into text.

Key mappings include:

• Structural/Block elements: <div>, <p>, <ul>, <ol>, <li>, <h1>-<h6>, <blockquote>, <table>, <tr>, <td>, <th>, <thead>, <tbody>.
• Inline/Text styling: <a> (Link), <em>/<i>/<ins> (Em), <strong>/<b> (Strong), <s>/<del> (Strikeout), <code> (Code), <sup> (Sup).
• Media/Special: <img> (Img), <svg> (Svg), <br> (Break).
• Lists: <ul> (Ul), <ol> (Ol), <dl> (Dl), <dt> (Dt), <dd> (Dd).

Some elements like <span> or <div> act as containers without adding specific text decorations, while others like <a> extract attributes (e.g., href) to create functional text nodes.

When the css_ext feature is enabled, the library can apply styles to specific text segments within a node.

During the conversion of markup5ever_rcdom::NodeData::Text, the library checks for extra_styles. If present, it splits the text into multiple RenderNode segments: some plain Text nodes and some Text nodes with a ComputedStyle (containing fg_colour and bg_colour). This allows for inline styling within a single text block.

The DOM uses reference counting to manage memory and allow nodes to exist independently of the document.

• Handle: A type alias for Rc<Node>. This is the standard way to hold a reference to a node.
• WeakHandle: A type alias for Weak<Node>. Used for parent pointers to prevent reference cycles that would cause memory leaks.