mdka

A HTML to Markdown converter written in Rust.

mdka balances conversion quality with runtime efficiency — correct, readable Markdown from real-world HTML, at competitive speed and near-flat 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. That is a claim about crashing, not speed — deep nesting still costs real time, quadratically; see Scaling: Depth and Width.
• Configurable pre-processing. Five conversion modes, of which two convert differently: Balanced (the default) and Minimal, which strips to body text and structure for LLM input. The other three are aliases of Balanced — 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:

| Platform | Asset | |---|---| | Linux x64 (glibc 2.17 or newer) | mdka@Linux-x64-gnu-<version>.tar.gz | | Linux x64 (musl, static) | mdka@Linux-x64-musl-<version>.tar.gz | | Linux aarch64 (musl, static) | mdka@Linux-aarch64-musl-<version>.tar.gz | | macOS Apple Silicon | mdka@macOS-aarch64-<version>.zip | | Windows x64 | mdka@Windows-x64-<version>.zip |

The glibc archive is built against glibc 2.17, so it runs on Ubuntu 20.04, Debian 11 and RHEL 8 as well as newer systems; the musl archives have no glibc requirement at all.

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

Prebuilt bindings are published for six platforms: Linux on x64 and arm64 (each with glibc and musl), macOS Apple Silicon, and Windows x64. macOS Intel and Windows ARM are not supported; the installation page lists what does work there.

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()

The Async functions cannot emit deprecation warnings, so an option that has been deprecated is reported only by the synchronous form (htmlToMarkdownWith). See Usage — Node.js.

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

| Mode | Use when | |---|---| | Balanced | General use — the default | | Minimal | LLM input, text extraction — the only mode that converts differently | | Strict, Semantic, Preserve | Aliases of Balanced; kept for compatibility |

Balanced, Strict, Semantic and Preserve produce identical output, and cannot differ. They vary only in the defaults of options that have no effect on Markdown — the format has no syntax for HTML attributes or wrapper elements — so there is no mechanism by which they could diverge. Choosing between them changes nothing. See Conversion Modes for the full explanation.

Tables convert to GFM tables. Column alignment is carried over, | in a cell is escaped, colspan/rowspan are expanded, and a cell holding block content is flattened (paragraphs join with <br>, a list becomes - one<br>- two). Four shapes have no Markdown expression and fall back to one paragraph per cell rather than a broken table: more than one header row, <th> used as each row's first cell, a nested <table>, and a <caption>. No table welds its cells together on either path. 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/

| Topic | Link | |---|---| | Installation | /getting-started/installation | | Rust Usage & Examples | /getting-started/usage-rust | | Node.js Usage | /getting-started/usage-nodejs | | Python Usage | /getting-started/usage-python | | CLI Reference | /getting-started/usage-cli | | API Reference | /api/index | | Conversion Modes | /api/modes | | ConversionOptions | /api/options | | Supported Elements | /api/elements | | Design Philosophy | /design/philosophy | | Performance Characteristics | /design/performance-characteristics | | Architecture | /design/architecture | | Features | /design/features | | Changelog | CHANGELOG.md | | Roadmap | ROADMAP.md |

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.