Archive layout and metadata
An .mdz file is a ZIP archive with conventions for entry-point discovery and optional metadata. This page summarizes the practical structure used by tools.
Minimum valid archive
The minimum conforming .mdz file is a ZIP archive with an .mdz extension containing at least one Markdown file resolvable as the entry point.
In practice, creation is straightforward: create a folder with at least one root-level .md file, compress it as .zip, then rename the file extension to .mdz.
MDZip defines a minimal, tool-agnostic format. Implementations may vary in how archives are created or processed.
index.mdat archive root is the recommended convention (if there is only one root-level Markdown file, not counting support files such asREADME.md, it can be named anything).manifest.jsonis optional for a valid archive, but tools that create.mdzfiles always write one.- Assets should be organized in named subdirectories at the archive root (e.g.
images/,styles/). A parentassets/folder is optional — useful when the archive grows large or complex, but not required.
Recommended structures
For a single-document archive:
document.mdz (ZIP archive)
├── index.md # Recommended: conventional entry point
├── manifest.json # Metadata and entry point (written by every MDZip tool)
├── README.md # Optional: human-facing usage notes
├── AGENTS.md # Optional: guidance for AI agents
├── images/ # Asset directories at archive root
│ └── cover.png
├── styles/
│ └── document.css
└── diagrams/
└── system.drawio
For a project-mode archive with multiple independently browsable Markdown pages:
project.mdz (ZIP archive)
├── index.md # Project landing page
├── manifest.json # Required for "mode": "project"
├── README.md # Optional: human-facing usage notes
├── AGENTS.md # Optional: guidance for AI agents
├── chapter.md # Additional Markdown files
├── reference.md
├── images/
│ ├── hero.png
│ └── architecture.svg
├── styles/
│ └── site.css
└── diagrams/
└── workflow.drawio
For larger or more complex archives, grouping under an assets/ parent is also valid in either mode:
document.mdz (ZIP archive)
├── index.md
├── manifest.json
├── README.md
├── AGENTS.md
└── assets/
├── images/
│ └── cover.png
├── styles/
│ └── document.css
└── diagrams/
└── system.drawio
Key archive entries
| Entry | Required | Purpose |
|---|---|---|
index.md |
No (recommended) | Conventional entry document for maximum interoperability. |
| Any Markdown file | At least one | Must be resolvable as the entry point via the discovery rules. |
manifest.json |
No (always written by tools) | Structured metadata about the document package, including its entry point. |
README.md |
No | Optional human-facing guide for recipients without .mdz tooling. |
AGENTS.md |
No | Optional guidance for AI agents and tools that open the archive without native .mdz support. See AGENTS.md below. |
images/, styles/, etc. |
No | Type-named asset folders at the archive root (recommended convention). |
AGENTS.md
AGENTS.md is an optional root-level file written for AI agents rather than people, the same idea as an AGENTS.md in a code repository. An AI assistant handed an .mdz may not know the format. This plain Markdown file, readable straight from the ZIP, tells it:
- to check first for an MDZip MCP server or another MDZip-aware tool, and use that for both reading and writing;
- how to find the main document, and what
"document"and"project"mode mean; - to read entries directly from the archive instead of extracting everything to a temporary folder;
- not to rewrite the archive with generic ZIP tools, which can't detect edits made elsewhere (for example in an open editor), and to ask you first.
It's advisory: when manifest.json is present, the manifest wins. Nothing else in the archive depends on AGENTS.md, so deleting it breaks nothing.
You don't have to write one yourself:
- MDZip Studio: File → Insert AGENTS.md. On a plain
.mdfile, Studio offers to convert it to.mdzfirst. - VS Code extension: run MDZip: Add AGENTS.md to Archive from the Command Palette, or right-click an
.mdzfile. MDZip: Convert .md To .mdz also offers to add one, and templates can include it.
Both add the same file; you can read the full template on GitHub.
Adding it doesn't change which document opens. Since spec 1.2.0, support files (README, AGENTS, LICENSE, CHANGELOG and CONTRIBUTING, as .md or .markdown) are set aside when tools look for the single root-level Markdown file. Older tools may still count them, so naming the main document index.md or setting entryPoint is still the safest choice.
Assets
Any file type can be packaged as an asset — the format does not restrict what you include. The recommended convention is type-named folders directly at the archive root (images/, styles/, diagrams/, etc.). An assets/ parent folder is optional and suits larger or more complex archives.
| Type | Examples | Notes |
|---|---|---|
| Raster images | .png, .jpg, .gif, .webp |
Photos, screenshots, illustrations |
| Vector graphics | .svg |
Icons and diagrams that scale without quality loss |
| Diagrams | .drawio |
Architecture or ER diagrams — package alongside a rendered export |
| Documents | .pdf |
Attachments, referenced specs, supporting material |
| Stylesheets | .css |
Rendering styles — consumers may choose to apply them |
| Data | .csv, .json, .yaml |
Data files referenced or described by the document |
| Code | .js, .py, .ts, etc. |
Source examples or snippets that are part of the content |
Consumers should treat .mdz content as untrusted input and must not execute scripts or binaries as part of normal rendering.
manifest.json
manifest.json lives at the archive root. Think of it as context for tools: title, entry point, authoring details, and document metadata.
An archive is valid without one, so a folder zipped by hand still works, and for hand-authored manifests no fields are strictly required. Every conforming producer tool, though, writes a manifest when it creates an archive, with at least spec.version and entryPoint, and should add title and mode.
The spec also provides a versioned JSON Schema companion. If you are building validation into a tool, use the schema directory and spec together: MDZip specification.
The table below covers the fields you'll use most often — it's a starting point, not the full schema. The specification also defines producer metadata and its nested fields, among others.
| Field | Required | Type | Notes |
|---|---|---|---|
spec.version |
Required for producers | String | Written by every conforming producer; semver string. |
title |
Recommended | String | Display title of the document package; if omitted, consumers should derive a title from context. |
mode |
Recommended | String | Interpretation mode: "document" (default) or "project". See Mode below. |
entryPoint |
Required for producers | String | The Markdown file to open first. Written by every conforming producer, so every tool opens the same file. |
author |
No | Object | Author metadata (for example name/email/url). |
description |
No | String | Short summary of archive purpose/content. |
keywords |
No | Array | Search and categorization metadata. |
{
"spec": {
"name": "mdzip-spec",
"version": "1.2.0"
},
"title": "My Project Documentation",
"mode": "document",
"entryPoint": "index.md",
"language": "en",
"author": { "name": "Jane Smith", "email": "jane@example.com" },
"description": "Full reference for the Acme Widget SDK.",
"version": "1.2.0",
"created": "2026-03-01T00:00:00Z",
"modified": "2026-03-08T14:30:00Z",
"license": "CC-BY-4.0",
"keywords": ["documentation", "sdk", "reference"],
"cover": "images/cover.png"
}
For normative rules and validation details, see the MDZip specification.
Entry point resolution
A conforming consumer will resolve the entry point in this order:
- If
manifest.jsonspecifiesentryPoint, open that file. If it names a file that isn't in the archive, or isn't a valid Markdown path, that's an error: the consumer must not quietly open a different file (it may offer to, with a visible warning). - Otherwise, if
index.mdexists at the archive root, open it. - Otherwise, if exactly one root-level Markdown file remains after setting aside support files (
README,AGENTS,LICENSE,CHANGELOG,CONTRIBUTING), open it. - Otherwise, treat the entry point as unresolved and surface an explicit error or user choice.
File names are matched exactly, including case: Index.md is not index.md. See the specification for the normative algorithm and edge cases.
Mode
The mode field in manifest.json tells consumers how to interpret the archive's contents.
| Mode | Meaning |
|---|---|
"document" |
A single logical document. This is the default when mode is absent or no manifest is present. |
"project" |
A collection of independent Markdown documents — for example an ebook, a documentation site, or a wiki. Requires an explicit manifest.json with "mode": "project". |
If mode is absent, consumers treat the archive as "document". Mode values are case-sensitive and must be lowercase.
A "project" mode archive with a minimal manifest:
{
"spec": {
"name": "mdzip-spec",
"version": "1.2.0"
},
"title": "Acme Widget SDK Docs",
"mode": "project",
"entryPoint": "index.md"
}
For full normative rules — including unrecognized mode handling and consumer support levels — see the MDZip specification.
Linking and references
Internal links between files use paths relative to the referencing file's location, not the archive root.
For example, a file at chapters/intro.md can reference an image with:

A conforming consumer must resolve that path against the location of the file containing the link — not the archive root — and match it exactly, including case.
A link that climbs above the archive root leaves the archive. Consumers treat it as unresolved unless they support links outside the archive, which is optional, read-only, and limited to a location the user trusts, such as an open vault or workspace. An archive that relies on such links is no longer self-contained, so keep anything the document needs inside it.
Security
A conforming consumer should treat .mdz content as untrusted input:
- No script or binary execution — consumers must not execute scripts or binaries found in the archive as part of normal rendering.
- Path traversal — reject archive entries whose names are absolute or contain
.., so nothing can be written outside the extraction folder. Links that leave the archive stay unresolved unless the consumer supports them, read-only, within a location the user trusts. - Prohibited characters — reject, rather than silently rename, entries whose paths contain null bytes, control characters, or OS-reserved characters.
- ZIP bombs — enforce reasonable limits on entry count, total uncompressed size, and compression ratio.
- External resources — consumers may warn before following external links, should let users turn off automatic loading of remote images, and should not load them over plain
http:. - Sensitive data — producers should not package credentials, private keys, or other sensitive data inside an archive.
This page renders from format.mdz (MDZip, ~7 KB, updated 2026-11-10) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.