html-to-markdown

Bindings Rust Python Node.js WASM Java Go C# PHP Ruby Elixir R Dart Kotlin Swift Zig C FFI License Documentation
html-to-markdown
Join Discord Live Demo

High-performance HTML to Markdown converter for Dart via flutter_rust_bridge. Pure-Dart binding (no Flutter SDK required) suitable for server and CLI workloads; Flutter apps can also consume it via the standard pub.dev workflow. Published as h2m on pub.dev because html_to_markdown and html-to-markdown are taken.

What This Package Provides

  • Same renderer as every binding — output matches Rust, Python, Node.js, Ruby, PHP, Go, Java, .NET, Elixir, R, Dart, Swift, Zig, C FFI, and WASM.
  • Structured conversion result — Markdown plus metadata, links, headings, images, tables, and warnings where the binding exposes them.
  • Production defaults — HTML is parsed with the Rust core, sanitized by default, and rendered without runtime-specific Markdown drift.
  • Dart package — flutter_rust_bridge API for Dart and Flutter projects.

Installation

dart pub add h2m

Performance Snapshot

Quick Start

Basic conversion:

import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
    show RustLib;

Future<void> main() async {
  await RustLib.init();

  const html = '<h1>Hello</h1><p>This is <strong>fast</strong>!</p>';
  final result = await H2mBridge.convert(html);
  print(result.content);
}

With conversion options:

import 'package:h2m/h2m.dart';
import 'package:h2m/src/html_to_markdown_rs_bridge_generated/frb_generated.dart'
    show RustLib;

Future<void> main() async {
  await RustLib.init();

  final options = await createConversionOptionsFromJson(
    json: '{"heading_style":"atx","list_indent_width":2,"wrap":true}',
  );

  const html = '<h1>Hello</h1><p>This is <strong>formatted</strong> content.</p>';
  final result = await H2mBridge.convert(html, options: options);
  print(result.content);
}

API Reference

Core Function

Options

ConversionOptions – Key configuration fields:

  • heading_style: Heading format ("underlined" | "atx" | "atx_closed") — default: "underlined"
  • list_indent_width: Spaces per indent level — default: 2
  • bullets: Bullet characters cycle — default: "*+-"
  • wrap: Enable text wrapping — default: false
  • wrap_width: Wrap at column — default: 80
  • code_language: Default fenced code block language — default: none
  • extract_metadata: Enable metadata extraction into result.metadata — default: false
  • extract_tables: Enable structured table extraction into result.tables — default: false
  • output_format: Output markup format ("markdown" | "djot" | "plain") — default: "markdown"

Djot Output Format

The library supports converting HTML to Djot, a lightweight markup language similar to Markdown but with a different syntax for some elements. Set output_format to "djot" to use this format.

Syntax Differences

Element Markdown Djot
Strong **text** *text*
Emphasis *text* _text_
Strikethrough ~~text~~ {-text-}
Inserted/Added N/A {+text+}
Highlighted N/A {=text=}
Subscript N/A ~text~
Superscript N/A ^text^

Example Usage

Djot's extended syntax allows you to express more semantic meaning in lightweight text, making it useful for documents that require strikethrough, insertion tracking, or mathematical notation.

Plain Text Output

Set output_format to "plain" to strip all markup and return only visible text. This bypasses the Markdown conversion pipeline entirely for maximum speed.

Plain text mode is useful for search indexing, text extraction, and feeding content to LLMs.

Metadata Extraction

The metadata extraction feature enables comprehensive document analysis during conversion. Extract document properties, headers, links, images, and structured data in a single pass — all via the standard convert() function.

Use Cases:

  • SEO analysis – Extract title, description, Open Graph tags, Twitter cards
  • Table of contents generation – Build structured outlines from heading hierarchy
  • Content migration – Document all external links and resources
  • Accessibility audits – Check for images without alt text, empty links, invalid heading hierarchy
  • Link validation – Classify and validate anchor, internal, external, email, and phone links

Zero Overhead When Disabled: Metadata extraction adds negligible overhead and happens during the HTML parsing pass. Pass extract_metadata: true in ConversionOptions to enable it; the result is available at result.metadata.

Example: Quick Start

Visitor Pattern

The visitor pattern enables custom HTML→Markdown conversion logic by providing callbacks for specific HTML elements during traversal. Pass a visitor as the third argument to convert().

Use Cases:

  • Custom Markdown dialects – Convert to Obsidian, Notion, or other flavors
  • Content filtering – Remove tracking pixels, ads, or unwanted elements
  • URL rewriting – Rewrite CDN URLs, add query parameters, validate links
  • Accessibility validation – Check alt text, heading hierarchy, link text
  • Analytics – Track element usage, link destinations, image sources

Supported Visitor Methods: 40+ callbacks for text, inline elements, links, images, headings, lists, blocks, and tables.

Example: Quick Start

Examples

Part of Kreuzberg.dev

  • Kreuzberg — document intelligence: text, tables, metadata from 90+ formats with optional OCR.
  • Kreuzberg Cloud — managed extraction API with SDKs, dashboards, and observability.
  • kreuzcrawl — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
  • liter-llm — universal LLM API client with native bindings for 14 languages and 143 providers.
  • tree-sitter-language-pack — tree-sitter grammars and code-intelligence primitives.
  • alef — the polyglot binding generator that produces every per-language binding across the 5 polyglot repos.
  • Discord — community, roadmap, announcements.

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Setting up the development environment
  • Running tests locally
  • Submitting pull requests
  • Reporting issues

All contributions must follow our code quality standards (enforced via pre-commit hooks):

  • Proper test coverage (Rust 95%+, language bindings 80%+)
  • Formatting and linting checks
  • Documentation for public APIs

License

MIT License – see LICENSE. Copyright © Kreuzberg, Inc.

Support

If you find this library useful, consider sponsoring the project.

Have questions or run into issues? We're here to help:

Libraries

h2m