What is an .mdz file?
An .mdz file is a ZIP archive with an .mdz extension and a defined structure for packaging one or more Markdown documents,
their assets, and optional metadata in a single self-contained file.
Think of MDZip (.mdz) like...
- Markdown that keeps its images - A markdown file with embedded images and assets.
- DOCX without Word - Why reach for Word when all you want is basic formatting with images?
- A ZIP file with rules - adds simple conventions so tools know how to open and interpret it.
- A portable Markdown project - a folder of
.mdfiles and assets in a single file. - EPUB for Markdown - a portable bundle of content with images, and metadata, but with Markdown instead of XHTML.
Quick Steps to Create an .mdz File:
1Markdown + images + whatever in a folder
➜
2 ZIP the folder
➜
3 Rename to .mdz.
Why not just ZIP?
A ZIP has no entry point, no metadata, and no predictable structure.
.mdz adds a flexible contract so tools can open the right file every time.
A conforming tool will usually create a manifest file to describe the contents and metadata of the .mdz archive (optional but recommended).
Quick Steps to View an .mdz File:
1 Rename the
.mdz file to .zip (or just open it with a ZIP tool directly).2 Open the main
.md file with a compatible viewer that can resolve relative paths.Common use cases
Markdown works well across tools until images are involved. MDZip addresses that gap.
- Cross-editor Markdown notes with images — Keep Markdown notes and their images portable across different editors and tools. Avoid broken image links when moving between note-taking apps or file structures, and enable consistent viewing (including file preview) without needing a specific application.
- Portable documentation bundle — Package Markdown docs, images, and attachments into a single file for sharing or distribution.
- Offline review package — Send a complete Markdown document set that can be opened and viewed without network access.
- Wiki or note export — Convert a wiki-style or note-taking project into a self-contained, tool-agnostic format.
- Book or article bundle — Combine multi-file Markdown content and illustrations into a single portable file.
- Static site source handoff — Package a Markdown-based project (e.g. MkDocs-style) for transfer, archiving, or later rendering.
The rest of this site describes the format, project, provides examples, and offers tools for creating and viewing .mdz files.