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, 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 .mdz file 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 machine
    

    or Chocolatey:

    choco install mdzip-studio
    

    On 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 .mdz in Finder then opens it in Studio. Or use Homebrew:

    brew install --cask mdzip-project/mdzip/mdzip-studio
    

    The 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 .deb on Debian, Ubuntu and distros based on them (Mint, Pop!_OS and others), and the AppImage on the rest. Either way it registers the .mdz file 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 | sh
    
  • 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, ~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.