Frequently Anticipated Questions

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 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.

Why not just use EPUB?

EPUB is ZIP-based too, but its content format is XHTML - not Markdown. Reading an EPUB requires a compatible reader. The XML internals are complex and tools are locked to specific apps.

.mdz can be thought of as an EPUB-like container for Markdown: same single-file packaging idea, but Markdown-native 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	`.mdz`
Content format	XHTML (XML)	Plain Markdown
Readable in a text editor (once extracted)	✅ (XHTML/XML noise)	✅ (clean Markdown)
Accessible without special reader (basic access)	❌	✅
Diff-friendly	❌	✅
Native Markdown tooling	❌	✅

Why diff-friendly? .mdz content is typically plain Markdown text, so version-control diffs stay readable. EPUB content is XHTML/XML, which tends to produce noisier structural diffs. The VS Code extension builds on this directly, with commands to compare the document or the whole archive against your Git base.

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.

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.

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 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.

Can an .mdz include HTML files?

Yes. HTML files can be included as assets like any other file type.

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.

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 .mdz to 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.

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. But, that means that if you need to do something tricky that Markdown doesn't handle natively (like use a css style or class), you can do that... although that really has nothing to do with .mdz.... except that you can package a stylesheet with your Markdown and well, now you have something cool.

What Markdown flavour 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.

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.

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.

Is the spec stable?

Yes. The current version is 1.1.0, and the specification status is final. The spec.version field in manifest.json carries the spec version (when emitted by a conforming producer), so tools can detect and adapt to future changes.

Read the full specification at github.com/mdzip-project/mdzip-spec.

Where can I find more Markdown resources?

Here are useful references:

This page renders from faq.mdz — one self-contained file. Download it, open it in the web editor, or read how these pages are made.