Download this page as .mdz

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.md at archive root is the recommended convention (if there is only one root-level Markdown file, not counting support files such as README.md, it can be named anything).
  • manifest.json is optional for a valid archive, but tools that create .mdz files always write one.
  • Assets should be organized in named subdirectories at the archive root (e.g. images/, styles/). A parent assets/ folder is optional — useful when the archive grows large or complex, but not required.

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 .md file, Studio offers to convert it to .mdz first.
  • VS Code extension: run MDZip: Add AGENTS.md to Archive from the Command Palette, or right-click an .mdz file. 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:

  1. If manifest.json specifies entryPoint, 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).
  2. Otherwise, if index.md exists at the archive root, open it.
  3. Otherwise, if exactly one root-level Markdown file remains after setting aside support files (README, AGENTS, LICENSE, CHANGELOG, CONTRIBUTING), open it.
  4. 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:

![Logo](../images/logo.png)

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.