Frequently Anticipated Questions
The format
Is this just a ZIP file?
Yes. An .mdz file is a standard ZIP archive. You can rename it to .zip and open it in any archive manager - no special software required. The .mdz extension signals the intent: this is a Markdown document package, not a generic archive.
Why not just send a ZIP with Markdown files inside?
You can! A bare .zip works fine for extraction. If the receiver is willing to unpack it and interpret it then you don't need .mdz. But it has no conventions: which file is the entry point? What's the title? What version of the spec was used? A purpose built tool will understand that and automatically do what is necessary.
.mdz adds a thin layer of agreed-upon structure - entry point discovery, optional metadata - without requiring any proprietary format.
MDZip defines a minimal, tool-agnostic format. Implementations may vary in how archives are created or processed.
Why not just use EPUB?
EPUB is ZIP-based too, but its content format is XHTML - not Markdown, and it's built for publication and reading systems rather than editing and authoring. Reading an EPUB requires a compatible reader; editing one is a specialist task, since the XML internals are more complex than plain Markdown and tools tend to be locked to specific apps.
.mdz can be thought of as an EPUB-like container for Markdown: same single-file packaging idea, but Markdown-native, authoring-oriented, and much lighter in structure.
Any tool that reads ZIP files can list an .mdz's contents without extracting anything. Once unzipped, the Markdown inside is plain text: any text editor can read it, and any programmer can parse it without a proprietary library. EPUB's XHTML is also plain text after unzipping - just noisier to read and edit by hand.
| EPUB | .mdz |
|
|---|---|---|
| Content format | XHTML (XML) | Plain Markdown |
| Readable in a text editor (once extracted) | ✅ (XHTML/XML noise) | ✅ (clean Markdown) |
| Editing-friendly (once extracted) | ⚠️ specialist tooling | ✅ any text editor |
| Native Markdown tooling | ❌ | ✅ |
What about diffs? Both are ZIP archives, so Git sees either one as a binary file. For
.mdz, themdzCLI'stextconvcommand makesgit diffshow the Markdown lines that changed inside the archive, and the VS Code extension compares an archive with your last commit. EPUB's XHTML gives noisier diffs even once extracted. Diffs on GitHub and Azure DevOps, merges and CI are covered in Using MDZip with Git, GitHub and Azure DevOps.
Why does MDZip use standard ZIP instead of 7z?
Some Markdown archive formats use 7z because it provides strong built-in encryption and, in certain cases, better compression. MDZip uses standard ZIP because its primary goal is broad interoperability.
ZIP is supported natively or through mature libraries across browsers, Windows, macOS, Linux, JavaScript, .NET, Python, Java, and most other development environments. This makes MDZip easier to implement in desktop applications, web applications, editor extensions, command-line tools, and automated systems.
Standard ZIP also provides a useful recovery path: an .mdz file can be renamed to .zip and opened with ordinary archive software, allowing its Markdown and assets to remain accessible even without an MDZip-specific application.
The compression advantage of 7z is usually limited for MDZip documents. Markdown compresses well with standard ZIP compression, while common assets such as JPEG, PNG, MP4, and PDF files are already compressed.
7z does offer a meaningful advantage for password-protected archives. MDZip does not currently define archive encryption because encryption support would reduce compatibility and require additional implementation dependencies. Encryption may be addressed later through an optional, explicitly defined profile or external security mechanism. To protect an .mdz file today, see Encrypting .mdz files.
In short, MDZip favors universal support, simple implementation, and long-term accessibility over maximum compression or built-in password protection.
What Markdown flavor does it use?
The spec doesn't mandate a specific Markdown variant. Authors should stick to CommonMark for maximum compatibility. GitHub Flavored Markdown (GFM) is a widely-supported superset and works well in practice.
Does CommonMark support HTML inside Markdown files?
Yes. CommonMark allows raw HTML blocks and inline HTML inside Markdown documents. In practice, rendering still depends on the consumer: some tools pass HTML through as-is, while others sanitize or restrict it for safety. That means you can reach for a CSS class or inline style when Markdown alone won't do it - which has nothing to do with .mdz specifically, except that you can package a stylesheet alongside your Markdown, and now you've got something genuinely useful.
Does it work offline?
An .mdz archive packages the Markdown and every asset it references, so nothing needs to be fetched over a network to resolve content. Whether a specific reader works fully offline depends on that tool — a web-based viewer may need its own code loaded once, while a native or CLI tool has no such requirement.
Is the spec stable?
Yes. The current version is 1.2.1, and the specification status is final. It changed nothing in the format from 1.2.0, so files written for either version are the same. The spec.version field in manifest.json carries the spec version (every conforming producer writes it), so tools can detect and adapt to future changes.
Read the full specification at github.com/mdzip-project/mdzip-spec.
What goes inside
Can I put non-Markdown files inside?
Yes. The spec doesn't restrict file types. Images, PDFs, CSVs, source code - any asset can be packaged. Tools are free to render what they understand and ignore what they don't.
Can an .mdz include the stylesheet used to render Markdown?
Yes. You can include stylesheets as assets (for example, assets/style.css). A viewer may choose to apply them, but the format does not require every reader to support custom CSS.
Can I put any file in an .mdz? Even code?
Yes. The format allows arbitrary asset types, including source code files. For interoperability and package size, producers should mostly include files that are actually referenced by the document.
Can an .mdz include HTML files?
Yes. HTML files can be included as assets like any other file type.
Can an .mdz hold a collection of documents, like a documentation site or ebook?
Yes. Set "mode": "project" in manifest.json and the archive is treated as a collection of independent Markdown documents rather than a single logical document. Consumers that support project mode can provide navigation across the files - a sidebar, table of contents, or direct file access - rather than flattening everything into one view.
document mode (the default) is for a single logical document. project mode is for multi-document collections like wikis, ebooks, or documentation sites.
Safety
Can an .mdz include malicious code?
It can contain malicious files as data, just like any ZIP container. Conforming readers should treat .mdz content as untrusted input and should not execute scripts or binaries as part of normal rendering.
Will HTML files be rendered automatically?
Not necessarily. Rendering behavior depends on the consumer. A basic .mdz reader may show HTML files as downloadable text assets, while more advanced tools may choose to preview them.
Can an .mdz trick an AI agent?
It can try. An archive may include an AGENTS.md file with guidance for AI agents, and every document in it is text an agent reads. In an archive from someone you don't know, that text is untrusted, like an email attachment: it could hold a prompt injection, instructions written to make an agent run commands, send data somewhere or change files you didn't ask it to. The specification says agents should follow AGENTS.md only for how to read and handle the archive, and should treat everything in the archive as data, not instructions. With an archive from someone else, use an agent that asks before running commands or editing files, and read what it proposes before you approve it.
Why does my browser warn when I download an .mdz file?
A legacy name collision: Microsoft Access (97–2003) once used .mdz for macro-capable wizard templates, and some browsers and email clients still carry that extension on their hardcoded caution lists. Opening an .mdz executes nothing — it's a ZIP of Markdown and media with no macro or scripting capability (though as with any archive, treat contents from unknown senders with normal caution). Full explanation and workarounds.
Websites
Could I package an entire website in an .mdz file?
If it's a Markdown-based site (like a MkDocs or Jekyll project), yes - that's a natural fit for project mode. The format still requires at least one Markdown file satisfying entry-point discovery; a pure static site with only HTML, CSS, and JS and no Markdown would not be a valid .mdz. Whether a reader renders packaged HTML as a website is implementation-specific.
If a website still needs HTML, why use .mdz at all?
If the content exists only to become one web page, you may not need .mdz. Plain Markdown with an assets folder, a CMS, or HTML directly will usually be simpler.
MDZip is useful when the document is also a portable artifact. The same .mdz can be opened in an editor, viewed offline, emailed, archived, versioned, downloaded, or rendered by different applications without separating the Markdown from its images and other assets. A website is then one consumer of the package rather than its only destination.
For a public, search-oriented website, a build process can render the .mdz once into static HTML and stable image files:
document.mdz -> HTML + web assets -> CDN
Visitors receive ordinary HTML; the server does not need to unpack the archive on every request. This is similar to generating HTML from Markdown, a CMS, or another source format.
The practical rule is:
- Website-only content: use Markdown, a CMS, or HTML directly.
- Portable content with embedded assets and multiple consumers: use
.mdz, then generate the appropriate delivery format. - Interactive archive viewing: deliver the
.mdzto a browser viewer. - SEO-critical public pages: deliver rendered HTML, regardless of the original source format.
MDZ is not intended to replace HTML. It replaces the fragile combination of Markdown plus separately managed assets when portability matters.
Should I render an .mdz to static HTML, or deliver the .mdz to the browser?
Both are valid ways to consume the same .mdz - pick by what the page actually needs.
Render to static HTML at build time when the content is public and should be fast, cacheable, and search-friendly. The build unpacks the archive once into plain HTML and stable asset files; visitors receive ordinary HTML that needs no JavaScript to read, and search engines and link unfurlers see the full content.
Deliver the .mdz to a browser viewer when SEO is not a concern and you want one of:
- Offline / local-first: load one archive and browse many documents with no further network requests.
- Single-file distribution: the document or doc set travels as one file you can download, email, version, or open from disk.
- Interactivity: a live editor, in-page search, or dynamic navigation over the archive.
A documentation library is a good example of the split: a public, indexed docs site renders to static HTML, while an offline or embedded help package ships the .mdz to a client viewer.
These modes are not exclusive. The same .mdz can be rendered into a static site, offered as a download, and opened in a browser viewer all at once - the website is one consumer of the package, not its only destination. The main trade-off for the shipped archive is that it is not crawlable and needs JavaScript for first paint; if you need SEO there too, you can pre-render HTML for crawlers and hydrate, at the cost of extra complexity.
Apps, licensing and resources
Can I use MDZip in my own app, even a paid one in an app store?
Yes, please do. That's what the libraries are for: every app that opens and saves .mdz makes every .mdz file more useful. The core libraries and the editor component are under the Apache License 2.0, which allows commercial and closed-source use, including paid apps in the Mac App Store, the iOS App Store, Google Play or the Microsoft Store. There's no fee and no need to ask. The license asks you to include a copy of it with your app; an "Open-source licenses" screen or file is the usual place.
The format is free to implement too. The specification is under CC BY 4.0, and the .mdz mark is public domain, so your app can use it for its document icon.
Why isn't MDZip Studio in the Mac App Store or Microsoft Store?
MDZip is a one-person open-source project, built in spare time, and every app store adds work: a review before every release and its own packaging rules. The Mac App Store also needs a paid developer membership (the same one that would remove the Open Anyway step), and MDZip avoids paid gatekeepers. Its apps must also run in a sandbox that limits how they open and save files. The Microsoft Store is free for individual developers, and a Store release would also remove the Windows download warnings, so it's being looked into.
For now, Studio is free from the places people already install software from:
- Windows: download it, or install it with WinGet or Chocolatey
- macOS: download it, or install it with Homebrew
- Linux: the install script, the
.debor the AppImage
If you'd rather get it from an app store, say so in Studio's issues. Enough people asking is what would make it worth doing.
What happens to my files if MDZip stops being maintained?
They still open. An .mdz is a standard ZIP file with Markdown inside, so any archive tool and any text editor can read it, with no MDZip software at all. The format doesn't depend on this project either: the spec is final and openly licensed, and the libraries are open source and share a set of test files that define what a valid .mdz is, so anyone can carry them on. More in Your files outlive us, and on how the project checks its AI-written code in Built in the open, with AI.
Is "Markdown" a trademark? Can I use the word?
Markdown is the name of a widely used markup language. We use the term descriptively to indicate content format compatibility.
The .mdz mark is being established by the MDZip project. MDZip is independent and is not affiliated with any Markdown-related trademark owner. If you plan to use "Markdown" as part of your own product or company name, do a trademark clearance search in your jurisdiction.
Where can I find more Markdown resources?
Here are useful references:
This page renders from faq.mdz (MDZip, ~9 KB, updated 2026-11-12) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.