mdka

A HTML to Markdown converter written in Rust.

mdka balances conversion quality with runtime efficiency — readable output from real-world HTML, without sacrificing speed or memory.
"ka" means "化 (か)" pointing to conversion.

Why mdka?

There are several good HTML-to-Markdown converters in the Rust ecosystem. mdka's specific focus is:

• Reliable output from diverse HTML sources. It is built on scraper, which uses html5ever — the HTML5 parser from the Servo browser engine. html5ever applies the same parsing algorithm that web browsers use, so it handles malformed tags, deeply nested structures, CMS output, and SPA-rendered DOM without special-casing.
• Crash resistance. Conversion uses non-recursive DFS throughout. There is no stack overflow, no matter the nesting depth.
• Configurable pre-processing. Five conversion modes let you tune what gets kept or stripped, from noise-free LLM input to maximum retention. Three of the five currently produce identical output — see Conversion Modes.
• Multi-language. The same Rust implementation is accessible from Node.js (napi-rs) and Python (PyO3).

Quick Start

Try it from the command line

Download a prebuilt binary (no Rust toolchain needed) from the latest release:

Other platforms (macOS Intel, Windows ARM, Linux aarch64 glibc) aren't built as binaries — use cargo install mdka-cli below instead.

Extract the archive; it contains one folder holding the mdka binary:

cd mdka@Linux-x64-gnu-<version>  # the folder the archive extracted to

echo '<h1>Hello</h1><p><strong>world</strong></p>' | ./mdka
# # Hello
#
# **world**

Or install via cargo — requires cargo (Rust language) installed:

cargo install mdka-cli

echo '<h1>Hello</h1><p><strong>world</strong></p>' | mdka
# # Hello
#
# **world**

mdka page.html                          # → page.md  (same directory)
mdka --mode minimal --drop-shell -o out/ *.html  # strip nav/header/footer
mdka --help                             # full option list

Add to a Rust project

# Cargo.toml
[dependencies]
mdka = "2"

use mdka::html_to_markdown;

let md = html_to_markdown("<h1>Hello</h1><p><em>world</em></p>");
// "# Hello\n\n*world*\n"

With options:

use mdka::html_to_markdown_with;
use mdka::options::{ConversionMode, ConversionOptions};

let html = "<nav>menu</nav><h1>Hello</h1>";
let mut opts = ConversionOptions::for_mode(ConversionMode::Minimal);
opts.drop_interactive_shell = true;
let md = html_to_markdown_with(html, &opts);
// "# Hello\n"

Add to a Node.js project

npm install mdka

const { htmlToMarkdown, htmlToMarkdownWithAsync } = require('mdka')

const md = htmlToMarkdown('<h1>Hello</h1>')
// "# Hello\n"

async function main() {
  const html = '<nav>menu</nav><h1>Hello</h1>'
  const minimal = await htmlToMarkdownWithAsync(html, {
    mode: 'minimal',
    dropInteractiveShell: true,
  })
  console.log(minimal)
}
main()

Add to a Python project

pip install mdka

import mdka

md = mdka.html_to_markdown('<h1>Hello</h1>')
# "# Hello\n"

html = '<nav>menu</nav><h1>Hello</h1>'
minimal = mdka.html_to_markdown_with(
    html,
    mode=mdka.ConversionMode.Minimal,
    drop_interactive_shell=True,
)

Conversion Modes

Balanced, Strict and Preserve currently produce identical output. They differ only in the defaults of five fields that have no effect, so choosing between them changes nothing today. They remain distinct API and may diverge again — see Conversion Modes, which explains why in full.

Tables are not yet converted. <table> cell text is emitted without structure or separators, so a table becomes a run of joined text. See Supported Elements for the full list of what is and is not supported.

Learn More

Full documentation is published as GitHub Pages, and its source lives in docs/.

https://nabbisen.github.io/mdka-rs/

Open-source, with care

This project is lovingly built and maintained by volunteers.
We hope it helps streamline your work.
Please understand that the project has its own direction — while we welcome feedback, it might not fit every edge case 🌱

Acknowledgements

Depends on scraper (+ html5ever), ego-tree, rayon, thiserror.

Also, napi-rs on binding for Node.js and PyO3's pyo3 / maturin on bindings for Python.