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, macOS, Linux) — the desktop editor. Download it, or install it from the command line as shown below. Studio's page has more on each system.
On Windows, use the installer, or the portable
.exe, which runs without installing. Installing for all users registers the.mdzfile type, so after that you just double-click the file, and you get a preview right in File Explorer. The app isn't signed with a certificate Windows recognizes, so the first time you run a downloaded installer or.exe, Windows may say Windows protected your PC: click More info, then Run anyway. To install it for all users from the command line, use WinGet:winget install MDZip.Studio --scope machineor Chocolatey:
choco install mdzip-studioOn macOS, download the
.dmg(one download for Apple Silicon and Intel Macs, macOS 12 or later), open it and drag MDZip Studio to Applications. Double-clicking an.mdzin Finder then opens it in Studio. Or use Homebrew:brew install --cask mdzip-project/mdzip/mdzip-studioThe app isn't signed by Apple, so the first time you open it macOS says it couldn't verify it. Click Done, then open System Settings → Privacy & Security and click Open Anyway. You only do this once. (Why isn't it signed?)
On Linux, this installs the
.debon Debian, Ubuntu and distros based on them (Mint, Pop!_OS and others), and the AppImage on the rest. Either way it registers the.mdzfile type, so files open in Studio from the file manager (a native Linux file-manager preview isn't available yet):curl -fsSL https://mdzip.org/install.sh | shVS 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
.mdzto.zipand extract. Inside is plain Markdown and ordinary image files. Because.mdzis 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 (), 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:
manifest.json'sentryPoint, if present. If it names a file that isn't there, tools report an error instead of opening something else.index.mdat the archive root, if present.- The single Markdown file at the archive root, if there's exactly one, not counting support files such as
README.mdorAGENTS.md. - 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
- Browse the tools — apps for everyone, libraries for developers.
- Read how the format works or the full specification.
- Building automation or using an AI assistant? See the AI Producer Guide.
This page renders from getting-started.mdz (MDZip, ~5 KB, updated 2026-11-10) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.