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

Built distributions (wheels)

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

Total release size: 5.2 MB

Release files / mdka-3.1.0.tar.gz

Download URL mdka-3.1.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
a4004e5e43a446604dca47ebd40ef205956bf5898a232da4b56e2e121c812c44
BLAKE2b-256 checksum
How to use checksums
b6e70803a06c1be634022a714bb773ca73377b5dbb121808a62df6c54d639ab9
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.0-cp310-abi3-win_amd64.whl

Download URL mdka-3.1.0-cp310-abi3-win_amd64.whl
Size 532.8 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
19ff35d490b7fb3f8e5c072bc0148b1c02ae137f897762fe280b0b48dada4af6
BLAKE2b-256 checksum
How to use checksums
dd1feddfe8c6f1acd2090c4f19f34543c1533245b2e9b275a2a1c026e7768d17
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.0-cp310-abi3-musllinux_1_2_x86_64.whl

Download URL mdka-3.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
Size 866.9 kB
Tags CPython 3.10 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
6988c9940a3488b41d7bc13484a1650ef3683c39ff0046149e0c6f35fe082ac5
BLAKE2b-256 checksum
How to use checksums
9bf5e65c446a7f3b044824aad94bdaea19db696c93050cd48e15964739acbe1a
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.0-cp310-abi3-musllinux_1_2_aarch64.whl

Download URL mdka-3.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
Size 815.0 kB
Tags CPython 3.10 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
f59ceae55eed1519aeeab08d5bbaea047d6c8df0a9e0c9dde002db15755ee897
BLAKE2b-256 checksum
How to use checksums
e571ec82c4a73463b00a2fd8befb3b9a4e57e88f0dbca236d8e3bf7f1d6460d2
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.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL mdka-3.1.0-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
29b3f362319000a78aa97de2fba12567101f9c2b08595c04b2891fa2bd583335
BLAKE2b-256 checksum
How to use checksums
55a3098ac166345d7ea28c3670c944e5d89278376159f07e5cbcfc3875763495
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.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL mdka-3.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 635.9 kB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
dec8b297d2db4360f7b29aa5dcb3161f8e3f698b23f8ac80255e976d360e68da
BLAKE2b-256 checksum
How to use checksums
68dd4d62c17a80cb9c8aeec5b20a57561ebdcc851173f628bf4b58990ad2c01a
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.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL mdka-3.1.0-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
43481d772c6998f5709c44e25cf3a383746ce297e352e90480b50f55bd664783
BLAKE2b-256 checksum
How to use checksums
3f414d9d9200b91ae32aa11644667058c10bbaa6f4e59c860cb25e2196dd7cc6
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.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.1.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