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 you can also run winget install MDZip.Studio --scope machine or choco install mdzip-studio, or use the portable .exe, which runs without installing); on Windows, installing for all users 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.
  • Obsidian — install the MDZip plugin from Obsidian's Community plugins and open the file in Obsidian's own editor, like a note.
  • 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     ← metadata (title, entry point, ...), written by MDZip tools
└── 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. If it names a file that isn't there, tools report an error instead of opening something else.
  2. index.md at the archive root, if present.
  3. The single Markdown file at the archive root, if there's exactly one, not counting support files such as README.md or AGENTS.md.
  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, ~3 KB, updated 2026-10-28) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.