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. For why .mdz suits AI tools in the first place, see What AI-friendly means.
The minimal valid archive
An .mdz is a standard ZIP archive (deflate or store) with an .mdz extension. The smallest valid archive is a single Markdown file at the root, with any name:
/
└── notes.md
That's valid on its own: with exactly one root-level Markdown file, there's no doubt which document to open.
The recommended minimum
For anything you produce, go one step further. Name the main document index.md and add a manifest:
/
├── index.md
└── manifest.json
With this manifest:
{
"spec": { "name": "mdzip-spec", "version": "1.2.0" },
"entryPoint": "index.md",
"title": "Minimal Example",
"mode": "document"
}
An archive is valid without either file, but as a producer you must write the manifest: spec 1.2.0 requires every tool that creates an archive to include manifest.json with spec.version and entryPoint, and recommends title and mode. It makes the archive self-describing, and mdz validate points it out when it's missing. index.md is the most widely recognized name for the main document, so people and older tools find it too.
Entry-point resolution
Consumers find the main document in this order:
manifest.json→entryPoint, if present. If it names a missing file or an invalid path, that's an error: consumers don't fall back to rules 2–4.index.mdat the archive root- The sole
.mdor.markdownfile at the archive root, not counting support files (README,AGENTS,LICENSE,CHANGELOG,CONTRIBUTING) - Otherwise: error — the archive has no unambiguous entry point
Rule of thumb for producers: name the main document index.md and declare it as entryPoint. The entryPoint is required; the name helps people and older tools.
Packaging assets
- Reference images with relative paths, resolved from the referencing file's location — not from the archive root. A file at
chapters/intro.mdreferences../images/logo.png, which resolves toimages/logo.pnginside the archive. - Every image and asset the document needs must resolve inside the archive. A path that climbs above the root (
../../logo.png) leaves the archive: consumers treat it as broken unless they support such links, and never load images from outside the archive by default. Don't produce them. - Forward slashes only. Case matters — treat paths as case-sensitive.
- Use type-named folders at the archive root (
images/,styles/, etc. — see the file format page for the full convention); anassets/parent folder is also valid, particularly for larger archives. Either way, only package files the document actually references.
Placing images
A plain Markdown image, , sits on its own line at its natural size. When an image needs a size or a position, use HTML in the Markdown, written the way MDZip's editors write it, so it looks the same in every app that opens the archive:
- Sized:
<img src="images/photo.webp" alt="Alt text" width="360" height="268"> - Text wrapping around it: add
align="right"(oralign="left") to the<img>. - Centered on its own line:
<p align="center"><img src="images/photo.webp" alt="Alt text"></p>
Don't use style="..." or rely on a stylesheet: MDZip apps remove inline styles for safety, and a stylesheet only works on the one site that has it. Always write alt text, and keep src a relative path inside the archive, as for any image.
Include an AGENTS.md
The archive you produce will often be read by another AI agent later, one that may not know the format. A root-level AGENTS.md tells that agent how to handle the archive safely:
- look for an MDZip MCP server (tools named
mdz_*, orupsert_canonical_document) or an MDZip-aware library first, for both reading and writing; - how to resolve the entry point and interpret
mode; - read entries from the archive in memory rather than extracting it to a temp folder;
- never rewrite the archive with generic ZIP tools, which can silently overwrite edits made elsewhere; ask the user first.
It's optional and advisory (the manifest stays authoritative), but it's cheap insurance. Don't write your own from scratch: copy the standard template verbatim. It's the same file MDZip Studio and the VS Code extension insert. See the file format page for what it contains.
Reading an archive someone else made? Check for AGENTS.md at the root before doing anything else with it, and follow it.
Common mistakes
- Wrapping everything in a top-level folder —
my-doc/index.mdinstead ofindex.mdat the root. Entry-point resolution fails. - Absolute or root-relative image paths (
/assets/x.png,C:\...) — use relative paths from the referencing file. - Manifest disagreeing with contents — an
entryPointthat doesn't exist in the archive. - Spaces-vs-encoding mismatches — the reference in the markdown must match the archive path exactly.
- Forgetting the images — packaging the markdown but not the files it references. Validators don't catch this yet, so check that every image path in the document is in the archive.
- Renaming a
.zipfull 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. Aim for output that passes validation without warnings, not just without errors.
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
.mdzfiles to use as templates: minimal, with images, and project mode. - This site publishes
llms.txtas 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 (MDZip, ~6 KB, updated 2026-11-10) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.