html2md

html2md is a Rust library and command-line tool that converts simple HTML documents into Markdown. It parses input with Servo’s html5ever engine and walks the resulting DOM to emit Markdown for headers, lists, quotes, tables, images, links, code, and inline formatting such as bold, italic, strikethrough, and underline. It is a practical choice when you need to turn rendered or stored HTML back into portable Markdown text.

What You Get

• A parse_html function that converts an HTML string into a Markdown string
• A standalone html2md command-line binary for one-off conversions
• Support for headers, paragraphs, nested lists, quotes, tables, images, links, and code
• Inline formatting handling for bold, italic, strikethrough, and underline
• A pluggable tag-handler design for customizing how specific elements are converted

Common Use Cases

• Turning stored or scraped HTML content back into portable Markdown
• Migrating CMS or email content from HTML into Markdown-based systems
• Generating Markdown documentation or previews from rendered HTML fragments

Under The Hood

Architecture

The crate centers on src/lib.rs, which drives conversion by parsing input with html5ever into a markup5ever_rcdom DOM and then recursively walking nodes. Element categories are handled by dedicated modules such as headers.rs, lists.rs, tables.rs, quotes.rs, images.rs, anchors.rs, paragraphs.rs, and styles.rs, each implementing a tag handler that emits the corresponding Markdown. A common.rs module and regex-based whitespace cleanup normalize the output, and src/bin/html2md.rs wraps the library as a CLI.

Tech Stack

It targets Rust edition 2018 and depends on html5ever 0.27 and markup5ever_rcdom for parsing, regex for whitespace correction, lazy_static for compiled patterns, and percent-encoding for URLs. The library exposes rlib, dylib, and staticlib crate types, and the release profile enables LTO with panic=abort. Dev dependencies include spectral, pretty_assertions, and indoc for tests.

Code Quality

The repo has a real test suite under tests/ with an integration harness plus focused files for lists, tables, quotes, images, iframes, and styles, alongside a test-samples fixture directory. Conversion logic is split cleanly per element type, which keeps handlers small and readable, though the maintenance badge marks the project as experimental and some Markdown flavor edge cases are explicitly unsupported.

API Design

The public surface is intentionally minimal: a single conversion entry point plus a customizable tag-handler mechanism for overriding element behavior. The CLI mirrors the library for shell use. Documentation is concise, primarily the README with a supported-features list, so common conversions are easy to reach while advanced customization requires reading the handler modules.