markitdown-mdzip
A MarkItDown plugin that converts MDZip (.mdz) archives to Markdown, and a markitdown-mdz command that goes the other way: Word, PowerPoint, HTML and more to .mdz, with the images kept.
An .mdz file is one or more Markdown documents and their images, packaged in a single ZIP file (specification). Without this plugin, MarkItDown treats an .mdz as a plain ZIP and lists every file in it, manifest.json included. With it, you get the document itself.
Install
pip install markitdown-mdzip
Use
Plugins are off by default in MarkItDown, so turn them on:
markitdown --use-plugins guide.mdz
markitdown --list-plugins # shows: mdzip
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=True)
result = md.convert("guide.mdz")
print(result.title)
print(result.markdown)
What you get
-
A document-mode archive (the usual kind) gives you its entry point: the main document, as the MDZip spec defines it.
-
A project-mode archive gives you every document. The entry point comes first. Each document starts with a comment naming its path, so the boundaries survive:
<!-- mdz:document path="guide/setup.md" --> # SetupSupport files at the archive root (
README,AGENTS,LICENSE,CHANGELOG,CONTRIBUTING) describe the package rather than its content. They're left out unless one of them is the entry point. -
The title comes from the archive's manifest, or else from the first
#heading.
Options
Pass these to convert():
| Option | Values | Default |
|---|---|---|
mdz_documents |
"auto", "entry", "all" |
"auto": "all" for project mode, otherwise "entry" |
keep_data_uris |
True / False |
False |
By default, image links keep their paths inside the archive (images/logo.png), which don't resolve once the Markdown is outside it. keep_data_uris=True embeds those images as data: URIs, so the output stands alone. It's the same option MarkItDown's Word and PowerPoint converters use.
md.convert("guide.mdz", keep_data_uris=True, mdz_documents="all")
Errors
The plugin follows the spec. It won't guess an entry point: an archive with two candidate documents at its root and no manifest isn't converted by this plugin. The same goes for invalid archives, which includes unsafe paths, encrypted entries, and sizes over the limits. MarkItDown then falls back to its generic ZIP converter.
The other direction: convert to .mdz
MarkItDown loses the images when it converts a Word or PowerPoint file to Markdown. The markitdown-mdz command keeps them: it writes an .mdz file holding the Markdown, with each image saved as its own file next to it.
pip install "markitdown-mdzip[docx,pptx]" # MarkItDown's Word and PowerPoint support
markitdown-mdz "Launch Notes.docx" # writes "Launch Notes.mdz"
markitdown-mdz deck.pptx -o slides.mdz
markitdown-mdz page.html --title "Trip Report"
Launch Notes.mdz
├── manifest.json
├── Launch Notes.md ← 
└── images/
└── image-001.png
from markitdown_mdzip import convert_to_mdz
result = convert_to_mdz("Launch Notes.docx")
result.save("Launch Notes.mdz")
print(result.entry_point, result.title, result.images)
How it works:
- MarkItDown runs with
keep_data_uris=True, so each image arrives embedded in the Markdown. - The tool decodes each embedded image into
images/image-001.png,image-002.jpg, and so on, and points the Markdown at that file. An image used twice is stored once. - The document is named after the source file (
Launch Notes.md). The name falls back toindex.mdwhen it can't be used as an archive path, or when it would be mistaken for a support file such asREADME.md. - The title is the one MarkItDown reports. If there isn't one, it's the document's first
#heading, then the file name.
It works for any format MarkItDown reads. Images come through for any format whose MarkItDown converter embeds them, which includes Word (.docx), PowerPoint (.pptx), and HTML pages with embedded images. MarkItDown's PDF converter extracts text only, so a PDF gives an .mdz without images.
| Option | CLI | Python |
|---|---|---|
| Output path | -o out.mdz (default: source name + .mdz) |
result.save(path) |
| Title | --title |
title= |
| Entry document name | — | entry_point= |
| Image folder | — | images_dir= (default images) |
| MarkItDown plugins | -p / --use-plugins |
pass your own markitdown=MarkItDown(...) |
| Overwrite | -f / --force |
— |
Development
python -m venv .venv
.venv/Scripts/python -m pip install -e ../mdzip-core-python -e ".[docx,pptx,pdf]" python-docx
.venv/Scripts/python -m unittest
Reading .mdz files is done by mdzip-core, the Python MDZip library. It has no dependencies of its own.
License
Apache-2.0
Metadata
Release files for markitdown-mdzip 0.1.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 | Provenance | Actions |
|---|---|---|---|---|
| markitdown_mdzip-0.1.0.tar.gz | 17.6 kB | With provenance | Details for markitdown_mdzip-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| markitdown_mdzip-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for markitdown_mdzip-0.1.0-py3-none-any.whl |
Total release size: 31.9 kB
Release files / markitdown_mdzip-0.1.0.tar.gz
| Download URL | markitdown_mdzip-0.1.0.tar.gz |
|---|---|
| Size | 17.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
06d71c49e0a56e17445bc83a24bb3764788f5d8634844628bf894be2b7dd340b
|
|
BLAKE2b-256 checksum How to use checksums |
979ae465f783c3aa67cf3b1b610ed2cbf3232e631586374f36a280e1cebc7e12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / markitdown_mdzip-0.1.0-py3-none-any.whl
| Download URL | markitdown_mdzip-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a989c37ec3946c9729ec61f2b2a670f120878526b69349a76005c0882a1e6362
|
|
BLAKE2b-256 checksum How to use checksums |
68fd49701145cd574fc9aa2acb16345d924a987ffde1e67a83d7567fdf7d682e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for markitdown-mdzip 0.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for markitdown_mdzip-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA 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.