Download this page as .mdz

Getting Started with MDZip

An .mdz file is a portable document: Markdown text plus every image it uses, packaged together in a single file. .mdz uses the widely supported ZIP container format with an open MDZip structure and specification.

Open an .mdz file

Pick whichever fits:

  • MDZip Studio (Windows, Linux) — download the installer; on Windows it registers the .mdz file type, so after that you just double-click the file, and you get a preview right in File Explorer. On Linux, the .deb registers the .mdz file type too, so files open in Studio from the file manager — a native Linux file-manager preview isn't available yet; an AppImage is also available for other distros.
  • VS Code — install the MDZip extension and open the file like any other.
  • In your browser, no install — drop the file into the web previewer.
  • Any archive tool — rename .mdz to .zip and extract. Inside is plain Markdown and ordinary image files. Because .mdz is a ZIP archive, standard ZIP tools can generally extract its contents without MDZip-specific software.

Create your first .mdz

With Studio

Create a new document, write, paste images right where you want them, save. The result is one .mdz file with everything inside.

In the browser

The packager turns a folder into an archive: drop a folder containing Markdown and images, download the .mdz.

With the CLI

Install mdz:

Windows (WinGet):

winget install MDZip.Cli

Windows (PowerShell) or macOS/Linux, if you'd rather not use a package manager — review the script before running it, same as any install-by-URL command:

irm https://raw.githubusercontent.com/mdzip-project/mdzip-cli/main/scripts/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/mdzip-project/mdzip-cli/main/scripts/install.sh | sh

Then package a folder:

mdz create my-notes -o my-notes.mdz --title "My Notes"

Validate it

Any of the tools will tell you if an archive has problems. From the command line:

mdz validate my-notes.mdz

What's inside

A minimal archive is just this:

my-notes.mdz  (a ZIP)
├── index.md          ← the document
├── manifest.json     ← optional metadata (title, entry point, ...)
└── images/
    └── photo.jpg     ← images, right where the markdown expects them

The Markdown references images with ordinary relative paths (![Photo](images/photo.jpg)), and because everything travels together, those references normally survive moving or sharing the archive.

How MDZip finds the document to open

A conforming archive MUST contain either a manifest that names the entry point, or a Markdown file discoverable by convention. Tools resolve it in this order:

  1. manifest.json's entryPoint, if present and valid.
  2. index.md at the archive root, if present.
  3. The single Markdown file at the archive root, if there's exactly one.
  4. Otherwise the archive is ambiguous — conforming tools MUST NOT guess; they'll ask you to pick an entry point, or you can add a manifest.
Archive state What happens Status
Manifest names an entry point Opens that file Conforming
No manifest, index.md at the root Opens index.md Compatible fallback
No manifest, exactly one root .md file Opens that file Compatible fallback
No manifest, multiple root .md files Reports ambiguity Warning or error
Manifest names a file that doesn't exist Rejected Invalid

This is the same algorithm every conforming tool implements — see Section 5.5 of the specification for the normative version.

Next steps

This page renders from getting-started.mdz (MDZip, ~2 KB, updated 2026-09-12) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.