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.3.0

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.3.0
File Size Uploaded Provenance Actions
mdka-3.3.0.tar.gz 1.2 MB Without provenance Details for mdka-3.3.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mdka 3.3.0
File Actions
mdka-3.3.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for mdka-3.3.0-cp310-abi3-win_amd64.whl
mdka-3.3.0-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for mdka-3.3.0-cp310-abi3-musllinux_1_2_x86_64.whl
mdka-3.3.0-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for mdka-3.3.0-cp310-abi3-musllinux_1_2_aarch64.whl
mdka-3.3.0-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.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
mdka-3.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for mdka-3.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
mdka-3.3.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for mdka-3.3.0-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 5.3 MB

Release files / mdka-3.3.0.tar.gz

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

Download URL mdka-3.3.0-cp310-abi3-win_amd64.whl
Size 533.8 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
cfc9264ec56bf83f81d210a52263d05dca2ca5f0899a8b764f405460e9ba2d88
BLAKE2b-256 checksum
How to use checksums
93c7de744d906a1ae0bc2beab39fa3629f47b91c31453f19fc012eb0f10880e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL mdka-3.3.0-cp310-abi3-musllinux_1_2_x86_64.whl
Size 870.5 kB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
83c28cf3079e927372d4c7f0b8b11bc83576cf401c95c26c7b5c4c80c2a9511f
BLAKE2b-256 checksum
How to use checksums
1004affa82f5a02ade2097bd10421136e6defdfe053ee05c398cf53be7524944
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL mdka-3.3.0-cp310-abi3-musllinux_1_2_aarch64.whl
Size 817.3 kB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
260ce0b88af179c19011ebf3604b81fe867e60f94592619866f194a370929286
BLAKE2b-256 checksum
How to use checksums
744e28329d7ba0d2766f7cd7e770a952a56c011257f4586bb67e1c8cad5c0cc2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL mdka-3.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 635.4 kB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
35c0d303590f7d2b8accccb2d8f98a17f6cba3a8b4c824199cb73e4ae440c14a
BLAKE2b-256 checksum
How to use checksums
36cc389046452a1d8cef847395917b8ff15e303ecb26b719a5492226dd14114d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL mdka-3.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 638.4 kB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
c422cf78c7f9103099dcf0cfc609071576670498d16b462c35df3201bb9273c5
BLAKE2b-256 checksum
How to use checksums
12a026deccece7f62efc94755285bad329f5a13a5304cc92cf47bbfbb5ee4a44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL mdka-3.3.0-cp310-abi3-macosx_11_0_arm64.whl
Size 568.3 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1cbd55cccf5105f63b085648c330df57cf7e1a12f3f27e40eaea0708027786f3
BLAKE2b-256 checksum
How to use checksums
6c9757f01240ec43fb5b91b99a9d50a051dad80370cf7c5fe2c1dddcb9deee90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","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.3.0

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.3.0 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