Skip to main content

mdka

A HTML to Markdown converter written in Rust.

crates.io npm pypi License
Documentation Dependency Status CI Executable npm PyPi

logo

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) and Minimal, which strips to body text and structure for LLM input. (Until 3.0 there were five; the other three were aliases of Balanced, 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.

Metadata

Release files for mdka 3.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mdka 3.1.1
File Size Uploaded Provenance Actions
mdka-3.1.1.tar.gz 1.2 MB Without provenance Details for mdka-3.1.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mdka 3.1.1
File Actions
mdka-3.1.1-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for mdka-3.1.1-cp310-abi3-win_amd64.whl
mdka-3.1.1-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for mdka-3.1.1-cp310-abi3-musllinux_1_2_x86_64.whl
mdka-3.1.1-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for mdka-3.1.1-cp310-abi3-musllinux_1_2_aarch64.whl
mdka-3.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for mdka-3.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
mdka-3.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for mdka-3.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
mdka-3.1.1-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for mdka-3.1.1-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 5.3 MB

Release files / mdka-3.1.1.tar.gz

Download URL mdka-3.1.1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
b8205e3946af068c728eb304a5eb4a484206b3af59ae2fbe9dc6d94829340f27
BLAKE2b-256 checksum
How to use checksums
78e3d0684077709f1ff47b3495028045c22c87912152250eb5d7a544243bfdae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-win_amd64.whl

Download URL mdka-3.1.1-cp310-abi3-win_amd64.whl
Size 533.0 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
00f82adf76020e73e8dd6f9575f6b711f68c527497356c863d9be2ccdf1d326f
BLAKE2b-256 checksum
How to use checksums
76a3edfc87158beb33036098535ca9cc7b6b5ce318b768bedbbb48d148a0a09d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL mdka-3.1.1-cp310-abi3-musllinux_1_2_x86_64.whl
Size 867.2 kB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
30f5217ff98b4988a1922fd38bf45e28fc878706c2e91724e5150c40e7551039
BLAKE2b-256 checksum
How to use checksums
805e11bad5b82c1c4f4282477b0694e5378cfb2c90deb0fe0016dde925ba26d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL mdka-3.1.1-cp310-abi3-musllinux_1_2_aarch64.whl
Size 815.4 kB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
2935b2544e6aa2d786db734f0d6fd7f8ef35953a58aef2e78219f83b9edc8a01
BLAKE2b-256 checksum
How to use checksums
642331f7486e2b925b3f2cab24d9d92f9c146e32318abca3b6fc399d26b13156
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL mdka-3.1.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 633.5 kB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
6d62453fe44c906e826db2eaf10b66ff4d72940ea14a0ce7ef0dd2f96eaccc40
BLAKE2b-256 checksum
How to use checksums
1f739f2b003045be21a5f5bed2587eb1f7d4f7afdbb0f533f61bd9754bf210b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL mdka-3.1.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 636.2 kB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
89679d79090e5e61c3441908e4351d5ac00070e825296546fc9674cb4000aa37
BLAKE2b-256 checksum
How to use checksums
6115a4281c36cf226a75b82480685b0457488e1745e8e79997f7859a51c2f593
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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.1.1-cp310-abi3-macosx_11_0_arm64.whl

Download URL mdka-3.1.1-cp310-abi3-macosx_11_0_arm64.whl
Size 567.8 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
cd342c6e745514e8773d815ee8af99bc60a09cf08fd0c6503dea2ab892449499
BLAKE2b-256 checksum
How to use checksums
600015acbc10e0f17be0a3c274e93ad2cda6aa91c6526d40e82848151ba7858b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","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}

Security for mdka 3.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.1 This release

7 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page