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 let you tune what gets kept or stripped, from noise-free LLM input to maximum retention. Four 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:
| Platform | Asset |
|---|---|
| Linux x64 (glibc) | mdka@Linux-x64-gnu-<version>.tar.gz |
| Linux x64 (musl) | mdka@Linux-x64-musl-<version>.tar.gz |
| Linux aarch64 (musl) | mdka@Linux-aarch64-musl-<version>.tar.gz |
| macOS Apple Silicon | mdka@macOS-aarch64-<version>.zip |
| Windows x64 | mdka@Windows-x64-<version>.zip |
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()
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 — default |
Strict |
Debugging, diff comparison |
Minimal |
LLM input, text extraction |
Semantic |
SPA content, ARIA-aware pipelines |
Preserve |
Archiving, audit trails |
Balanced, Strict, Semantic and Preserve currently produce identical
output. They differ only in the defaults of fields that have no effect
today, so choosing between them changes nothing today. They remain distinct
API and may diverge again — see
Conversion Modes, which explains
why in full.
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.
1 maintainer
Release files for mdka 2.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mdka-2.5.0.tar.gz | 995.8 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| mdka-2.5.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| mdka-2.5.0-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| mdka-2.5.0-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| mdka-2.5.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| mdka-2.5.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| mdka-2.5.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 5.0 MB
Release files / mdka-2.5.0.tar.gz
| Download URL | mdka-2.5.0.tar.gz |
|---|---|
| Size | 995.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99c241d528c0e0d037e558f1816923b95c247d6ea4b9ef6405d5434b0b19b8ad
|
|
BLAKE2b-256 checksum How to use checksums |
e26d9f857f9bf0590eb601f85b828b04264f9b6422b9e12ce0b4175989f0d67f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-win_amd64.whl
| Download URL | mdka-2.5.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 531.1 kB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
486b1859baf4cae0d2f8a99be57eff572dda0b7af130c4901f9f4f6eb5d88640
|
|
BLAKE2b-256 checksum How to use checksums |
4bf85d4c894909ff733135fb8eb4a7071f72d177a2ac39bea39eb62cd990bfdc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | mdka-2.5.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 864.8 kB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3b6c760f216efdba67fa27d76611706f8ee1153dc7a14d725d05fa0c1fd63db7
|
|
BLAKE2b-256 checksum How to use checksums |
5b4b237c918dc91a54d357a10c19a28ca878f21f0d29784b58930873b8bb75c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | mdka-2.5.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 813.0 kB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
ac3a5642f2e7646604259142bc315974ce916b69a5549288d80de986df11261e
|
|
BLAKE2b-256 checksum How to use checksums |
ef22b6c6d90d9cc3c7bd957b868a74450748c49e3efff58ca788bff57af2038f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | mdka-2.5.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 631.2 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
17e1e680ac11b272f6a2a838feabef35f0c1631e702d363a76e8303442120411
|
|
BLAKE2b-256 checksum How to use checksums |
19617340e92951e0f66624777aa2da18a93b73d3173a62de69e55ff4af620c7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | mdka-2.5.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 633.7 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
1cfebb5bd7ca604a37b9717e0345b4544eb02ea66b4759507999934bffc789ba
|
|
BLAKE2b-256 checksum How to use checksums |
32c2e08b872d140c37b8065bedeee2ec957ff28d8d47efe64edbe9481716a3b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mdka-2.5.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | mdka-2.5.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 564.6 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
df8859eb46df3e1f27c7ceea0786b456cf2302b2b8661b3475e53c450d88266c
|
|
BLAKE2b-256 checksum How to use checksums |
d0aa7f0d33a60cfc75ac00ec7275ae531bc87b72fc28e0a74c39a001b46d0fba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
