Getting Started with MDZip

An .mdz file is a portable document: Markdown text plus every image it uses, packaged together in a single file. Under the hood it's a standard ZIP archive — nothing proprietary, nothing to install to get your content back out.

Open an .mdz file

Pick whichever fits:

• MDZip Studio (Windows) — download the installer; it registers the .mdz file type, so after that you just double-click the file. You also get a preview right in File Explorer.
• 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. This always works, everywhere, forever.

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:

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, ...)
└── assets/
    └── photo.jpg     ← images, right where the markdown expects them

The Markdown references images with ordinary relative paths (![Photo](assets/photo.jpg)), and because everything travels together, those references can never break.

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 — one self-contained file. Download it, open it in the web editor, or read how these pages are made.