Resources for builders
The spec includes non-normative implementation guidance in
Section 16
to help tool authors and AI-assisted coding agents implement .mdz
support consistently.
Adding .mdz to an existing app? Start with
Add MDZip to your app: the libraries to use, tested code
for opening, exporting and saving, and ready-made prompts for AI coding assistants.
Producer checklist
When creating an .mdz archive:
- Collect source Markdown and assets in a staging tree
- Normalize text encoding to UTF-8 for Markdown and JSON files
- Normalize line endings to LF in Markdown files and
manifest.json; leave other files as they are
- Validate file paths against Section 5.4 constraints
- Write
manifest.json with spec.version and entryPoint (plus title and mode), verify entryPoint names a Markdown file in the archive, and preserve unknown fields when rewriting an existing manifest
- When modifying an existing archive, confirm the entry point still resolves to the same file
- Report links that point outside the archive to the author as a notice; don't rewrite them
- Create an unencrypted ZIP archive with the
.mdz extension
Consumer checklist
When opening an .mdz archive:
- Open as ZIP and reject encrypted/password-protected entries
- Enumerate entries and validate path safety constraints; reject rather than rename
- Parse
manifest.json if present; reject unsupported spec.version major versions; keep unknown fields; don't require a manifest
- Resolve the primary Markdown file via the entry point discovery algorithm: a missing or invalid
entryPoint is an error, never a silent fallback; set aside support files such as README.md
- Parse Markdown with UTF-8 decoding; accept LF and CRLF
- Resolve relative links against the referencing file's path, matching paths exactly (case-sensitive); links that leave the archive stay unresolved unless supported within a trusted location
- If no unambiguous entry point exists, show an explicit error or user choice — do not silently auto-pick
Recommended archive layout
A typical .mdz archive keeps content and assets organized like this:
document.mdz/
|-- index.md # recommended entry point
|-- manifest.json # metadata and entry point (always written by tools)
|-- chapter.md # additional markdown files
|-- assets/ # images, styles, media
|-- images/
|-- styles/
Suggested error constants
Standardised error identifiers make cross-tool debugging easier:
ERR_ZIP_INVALID // not a valid ZIP, or a compression method other than 0 or 8
ERR_ZIP_ENCRYPTED // archive or entries use unsupported encryption
ERR_PATH_INVALID // entry path violates Section 5.4 constraints
ERR_PATH_CONFLICT // a file's path is also another entry's directory
ERR_DUPLICATE_PATH // two entries with the same path after NFC normalization
ERR_MANIFEST_INVALID // manifest.json is not JSON, or a critical field is invalid
ERR_ENTRYPOINT_UNRESOLVED // no unambiguous primary Markdown file found
ERR_ENTRYPOINT_INVALID // entryPoint is not a valid Markdown file path
ERR_ENTRYPOINT_MISSING // entryPoint names a file not in the archive
ERR_VERSION_UNSUPPORTED // manifest spec.version major version not supported
ERR_MODE_UNSUPPORTED // manifest mode is not supported or not recognized
Building with AI assistance
The spec includes guidance for AI-assisted implementation. For best results, include in your prompt:
- The exact target spec version (currently
1.2.1)
- Whether you are implementing a producer, consumer, or both
- Your required conformance scope (minimum MUSTs vs. SHOULDs included)
- Required behavior for ambiguous entry points
- Explicit test expectations from the spec's shared conformance fixtures
Useful libraries
Start with an MDZip core library if your language has one: it reads, writes and validates .mdz files and is tested against the spec's shared fixtures. The cores don't render Markdown, so you'll also want a renderer. In JavaScript you can skip both: the MDZip editor opens an .mdz and shows it, images included, as a read-only viewer or a full editor. For other languages, use a ZIP library and follow the conformance checklist; it lists the ZIP rules that catch most implementations out, such as libraries that always write ZIP64.
Missing your language? A core library for it is a good first project, and there's a ready-made prompt for having an AI assistant build one against the shared tests.