Download this page as .mdz

AI Producer Guide

Practical guidance for AI assistants and automated tools that generate .mdz archives. The specification is the law — it defines what a conforming archive is. This page is the cookbook: how to produce one correctly on the first attempt.

The minimal valid archive

An .mdz is a standard ZIP archive (deflate or store) with a .mdz extension. The smallest useful conforming archive:

/
├── index.md
└── manifest.json

With this manifest:

{
  "spec": { "name": "mdzip-spec", "version": "1.1.0" },
  "entryPoint": "index.md",
  "title": "Minimal Example",
  "mode": "document"
}

Strictly, manifest.json is optional — a bare ZIP containing one root index.md validates — but producers should always write one: it makes the archive self-describing (title, entry point, mode) and validators stop warning about it.

Entry-point resolution

Consumers find the main document in this order:

  1. manifest.json → entryPoint, if present and valid
  2. index.md at the archive root
  3. The sole .md file at the archive root
  4. Otherwise: error — the archive has no unambiguous entry point

Rule of thumb for producers: name the main document index.md and also declare it as entryPoint. Belt and suspenders.

Packaging assets

  • Reference images with relative paths, resolved from the referencing file's location — not from the archive root. A file at chapters/intro.md references ../images/logo.png, which resolves to images/logo.png inside the archive.
  • Every referenced path must resolve inside the archive. Paths that traverse outside the root (../../evil.png) must be rejected by consumers and must never be produced.
  • Forward slashes only. Case matters — treat paths as case-sensitive.
  • Put assets in a folder (conventionally assets/) rather than loose at the root, and only package files the document actually references.

Common mistakes

  1. Wrapping everything in a top-level folder — my-doc/index.md instead of index.md at the root. Entry-point resolution fails.
  2. Absolute or root-relative image paths (/assets/x.png, C:\...) — use relative paths from the referencing file.
  3. Manifest disagreeing with contents — an entryPoint that doesn't exist in the archive.
  4. Spaces-vs-encoding mismatches — the reference in the markdown must match the archive path exactly.
  5. Forgetting the images — packaging the markdown but not the files it references. Validators flag these as missing assets.
  6. Renaming a .zip full of arbitrary files to .mdz — there must be at least one Markdown document satisfying entry-point resolution.

Validate before delivering

Always validate generated archives:

mdz validate generated.mdz

Or open the archive in the web previewer — validation problems surface immediately. A conforming producer's output passes validation without warnings.

Machine-readable resources

  • Specification (raw Markdown): https://raw.githubusercontent.com/mdzip-project/mdzip-spec/main/SPEC.md
  • Manifest JSON schema: mdzip-spec/schema
  • Example archives — canonical, validating .mdz files to use as templates: minimal, with images, and project mode.
  • This site publishes llms.txt as a machine-readable index of these resources.

For humans reading this

If you're asking an AI assistant to produce an .mdz, a prompt that works well:

Using the MDZip specification at https://mdzip.org/spec.html, create a valid
.mdz archive containing this document and all referenced images.

Then validate the result with any MDZip tool — see Getting Started.

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