Skip to main content

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" -->
    
    # Setup
    

    Support 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)
└── 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 to index.md when it can't be used as an archive path, or when it would be mistaken for a support file such as README.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)

Source distribution for markitdown-mdzip 0.1.0
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)

Table of built distributions (wheels) for markitdown-mdzip 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

0.1.0 This release

2 release files Full 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