.mdzA portable, open format for bundling Markdown documents, images, and metadata into a single ZIP archive.
.mdz file?
A .mdz file is a standard ZIP archive with a
.mdz extension, structured to contain one or more
Markdown documents along with their associated assets and optional
metadata — all in a single, self-contained file.
All Markdown content, images, and linked assets are bundled together. No broken links, no missing files.
Built on the widely supported ZIP format. Any ZIP tool can open, inspect, or extract a .mdz file.
The primary content is plain Markdown — human-readable and renderable anywhere. Images and other assets travel alongside it in the same archive.
Share a single file via email, file storage, or any transfer method and the recipient gets everything they need.
An optional manifest.json allows tools to store title, authors, dates, keywords, license, and custom fields.
Designed to integrate with Markdown renderers, static site generators, and documentation tools. The format is open — the ecosystem just needs to adopt it.
.mdz?
Markdown is great for writing, but sharing a document with images
and multiple files means sending a folder, a repo link, a ZIP, or a
tarball — none of which are friendly to non-technical recipients.
.mdz solves this — and even on a system with no
knowledge of the format, the file remains immediately accessible:
rename it to .zip, extract, and open the Markdown in
any text editor.
Attach a single .mdz to an email or upload it anywhere. The recipient gets the complete document — no zip-then-rename, no folder compression ambiguity.
Unlike proprietary formats (DOCX, Notion exports, Confluence backups), .mdz is plain text in a standard ZIP. Any tool can read it today and in ten years.
A recognised extension and a defined layout give tools a contract to rely on — so renderers, editors, and converters can handle .mdz without guessing at the contents.
On any system that can unzip files and open a text editor, a .mdz file is immediately useful. Rename it to .zip, extract, and read. No special software, no installation, no internet required.
.mdz compare?Several formats can carry document content as a single file. None of them tick every box that a portable, author-friendly Markdown bundle needs to.
Folder of.md files |
Bare.zip |
DOCX | EPUB | Markdown Zip.mdz |
||
|---|---|---|---|---|---|---|
| Single file | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Plain text inside | ✅ | 🟡 | 🟡 | 🟡 | ❌ | ✅ |
| Readable without special software | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
| Defined structure | ❌ | ❌ | 🟡 | ✅ | 🟡 | ✅ |
| Markdown-native | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Version-control friendly | ✅ | 🟡 | ❌ | ❌ | ❌ | ✅ |
✅ yes · ❌ no · 🟡 partial · DOCX and EPUB are ZIP-based with XML/HTML inside, not Markdown. "Readable without special software" means the text content is accessible with a text editor and a ZIP tool alone — inter-file links and full rendering require a dedicated viewer for any format.
A valid .mdz archive must contain at least one
Markdown file resolvable as the entry point. Placing
index.md at the root is the recommended convention —
consumers use a defined discovery algorithm to locate the entry
point, with index.md as the first fallback.
| Entry | Required | Description |
|---|---|---|
index.md |
No (recommended) | The conventional entry point. Consumers resolve the primary document via a defined discovery algorithm; placing index.md at the root is the most interoperable approach. |
manifest.json |
No | JSON metadata: title, authors, version, description, keywords, and more. When present, mdz and title are required fields. |
assets/ |
No | Recommended directory for images, styles, and other media referenced in Markdown files. |
Additional .md files |
No | Extra Markdown files linked from index.md, at any path within the archive. |
manifest.json file
Place a manifest.json at the archive root to provide
structured metadata about the document bundle. When present,
mdz (a semver string) and title are
required; all other fields are optional.
{
"mdz": "1.0.0",
"title": "My Project Documentation",
"entryPoint": "index.md",
"language": "en",
"authors": [
{ "name": "Jane Smith", "email": "jane@example.com" }
],
"description": "Full reference for the Acme Widget SDK.",
"version": "1.2.0",
"created": "2026-03-01T00:00:00Z",
"modified": "2026-03-08T14:30:00Z",
"license": "CC-BY-4.0",
"keywords": ["documentation", "sdk", "reference"]
}.mdz file
Because .mdz is a ZIP archive, you can create one
with any standard ZIP tool — no special software required.
The minimum conforming .mdz file is just an
index.md inside a ZIP archive with the extension
renamed to .mdz. Everything else is optional.
Want to start from a working example? The spec repository includes
sample archives
— minimal, with manifest, and with assets.
Write your Markdown
Create an index.md file with your document content using standard Markdown syntax.
Add a manifest (optional)
Create a manifest.json with title, author, and other metadata you want to include.
Gather assets
Place any referenced images or other media in an assets/ subdirectory and update your Markdown image paths accordingly.
Zip it up
Compress the files into a ZIP archive and rename the extension from .zip to .mdz.
# Create the directory structure
mkdir -p my-doc/assets
# Write your document
echo "# Hello World" > my-doc/index.md
# Add an image
cp photo.png my-doc/assets/photo.png
# Zip and rename to .mdz
cd my-doc && zip -r ../my-doc.mdz . && cd ..# Create structure
New-Item -ItemType Directory my-doc\assets
# Write your document
"# Hello World" | Out-File my-doc\index.md
# Compress to .mdz
Compress-Archive -Path my-doc\* -DestinationPath my-doc.mdz