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...
One document
- Markdown that keeps its assets - A Markdown file bundled with everything it references — images, SVGs, diagrams, PDFs, stylesheets.
- DOCX without Word - Why reach for Word when all you want is basic formatting with images?
- EPUB for Markdown - a portable bundle of content with images, and metadata, but with Markdown instead of XHTML.
Or a whole project
- A portable Markdown project - an ebook, a documentation site, a wiki — a folder of
.mdfiles and assets bundled into a single file.
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
One document
- Cross-tool Markdown documents with assets — Keep any Markdown file — notes, prompts, READMEs, agent context, reports — portable with its images, diagrams, PDFs, and stylesheets across editors and tools. Avoid broken asset references when moving between apps or file structures, and enable consistent viewing without needing a specific application.
Or a whole project
- Book — Each chapter as its own
.mdfile, bundled with a cover image, illustrations, and assets into a single portable file. - Multi-page documentation — A MkDocs-style docs site with each section as a separate file, packaged for sharing, archiving, or later rendering.
- Markdown-based website — A complete
.md-based site bundled into a single file for handoff, backup, or offline use.
The rest of this site describes the format, project, provides examples, and offers tools for creating and viewing .mdz files.