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.
Two conversion modes:
Balanced(the default) andMinimal, which strips to body text and structure for LLM input. (Until 3.0 there were five; the other three were aliases ofBalanced, and were removed.) - 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. Replace
<version> with the release you downloaded (for example 2.6.0).
Linux — use your archive's name (Linux-x64-gnu, Linux-x64-musl or
Linux-aarch64-musl) in the first two lines:
tar xzf mdka@Linux-x64-gnu-<version>.tar.gz
cd mdka@Linux-x64-gnu-<version>
echo '<h1>Hello</h1><p><strong>world</strong></p>' | ./mdka
# # Hello
#
# **world**
macOS:
unzip mdka@macOS-aarch64-<version>.zip
cd mdka@macOS-aarch64-<version>
echo '<h1>Hello</h1><p><strong>world</strong></p>' | ./mdka
# # Hello
#
# **world**
Windows (PowerShell):
Expand-Archive mdka@Windows-x64-<version>.zip -DestinationPath .
cd mdka@Windows-x64-<version>
'<h1>Hello</h1><p><strong>world</strong></p>' | .\mdka.exe
# # 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, htmlToMarkdownAsync } = require('mdka')
const md = htmlToMarkdown('<h1>Hello</h1>')
// "# Hello\n"
async function main() {
const html = '<nav>menu</nav><h1>Hello</h1>'
const minimal = await htmlToMarkdownAsync(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 — the default |
Minimal |
LLM input, text extraction — the only mode that converts differently |
There were five modes until 3.0. Strict, Semantic and Preserve were
aliases of Balanced — byte-for-byte the same output — and were removed; asking
for one by name is now an error that says so. 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.
1 maintainer
Release files for mdka 3.0.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-3.0.0.tar.gz | 1.1 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| mdka-3.0.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| mdka-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| mdka-3.0.0-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| mdka-3.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| mdka-3.0.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| mdka-3.0.0-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 5.2 MB
Release files / mdka-3.0.0.tar.gz
| Download URL | mdka-3.0.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d7ce4d4cd203af5929baae01d9323cffe4e2f4dd20196f4749cea1076ee393b
|
|
BLAKE2b-256 checksum How to use checksums |
cd767dc892f275876abe0da7ca126869b1a4eb403a3f65c4a80f164bdbdeefe8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-win_amd64.whl
| Download URL | mdka-3.0.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 |
13ee6dbbabfa342aa559fde16a5d99f2b34fa002df94371c6be343c70376cecf
|
|
BLAKE2b-256 checksum How to use checksums |
ad5e13d8ef9bad9f1b97f5d69f973d117a3674a3787b54d294f41865ae38dcf9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | mdka-3.0.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 864.9 kB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
67ffc16115de7116285c2cea6c525b22fbbbf0abd303302ec12ecd2998cf1de8
|
|
BLAKE2b-256 checksum How to use checksums |
8ec6fb772c1dc14753f0ffb9491f3fff064e213b923be3777f425d642d955548
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | mdka-3.0.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 814.1 kB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
665b0ad37620c231850a60e4a62d7b2e17e739d6c412af6c27c8264d06231974
|
|
BLAKE2b-256 checksum How to use checksums |
539c3c86dd2d33a9205e5cda4cd946e71e99cc28b622cf7c7eefa23fb571b4e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | mdka-3.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 631.9 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
272277b487972a1fb228a2b062b500354a67b9d3bc521da66351f23c67a83c75
|
|
BLAKE2b-256 checksum How to use checksums |
751c1e3df33cdd582da0a5d2056b4811d0da3ec94ab822ad418f2aaf55bf389c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | mdka-3.0.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 634.9 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
9d759c5cca6e8ac74b12b3452ef1ee0478ac8a1a2e437b7fe958709a8f0af694
|
|
BLAKE2b-256 checksum How to use checksums |
80209d0e3da7b94fd2042d21c8efa79ab0b4e2db7d13fe283e0873cf8d8f8648
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.0.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | mdka-3.0.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 566.6 kB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f541acf145d8f3d045786a51e05428c156f03c922132248e993ba820329ee1c5
|
|
BLAKE2b-256 checksum How to use checksums |
4f34d1754df357d34a684698d19eeccb9b02526d99929fd88572a1513839b1b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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}
|
