MDZip Specification

Specification for the MDZip (.mdz) file format.

Current release: v1.1.0 (dated 2026-04-05).

This repository defines the .mdz file format specification; it does not provide an editor, viewer, or reference implementation.

What is .mdz?

An .mdz file is a portable, self-contained document format that packages one or more Markdown content files together with their associated assets (images, stylesheets, etc.) into a single ZIP archive.

Specification

Read the full specification: SPEC.md

The specification covers:

• File format - ZIP-based archive structure and encoding requirements
• Archive layout - Required and recommended file organization
• Manifest - Optional manifest.json metadata, entry-point override, and mode declaration
• Modes - document (default) and project interpretation modes
• Markdown content - Encoding, dialect guidance, and multi-page support
• Assets - Bundling images and other resources
• Linking - How to reference files within the archive
• MIME type - Proposed application/vnd.mdzip with the .mdz extension
• Versioning - Semantic versioning of the spec and compatibility rules
• Conformance - Requirements for producers and consumers

Repository Contents

• SPEC.md - canonical format specification
• examples/ - sample valid and invalid package structures
• tests/ - conformance case catalog and expected behavior
• schema/ - versioned JSON Schema companion for manifest validation
• reference/ - non-normative notes and rationale
• CHANGELOG.md - project change history
• CONTRIBUTING.md - contribution process

Quick Start

A minimal .mdz file is a ZIP archive (renamed with a .mdz extension) containing:

1. index.md at the archive root (for a single .md file, it can have any valid name. index.md will take precedence if there are multiple files and no manifest):

   # My Document
   
   Hello from MDZip!

2. (Optional) manifest.json for metadata and entry-point override:

   {
     "spec": {
       "name": "mdzip-spec",
       "version": "1.1.0"
     },
     "title": "My Document",
     "entryPoint": "index.md"
   }

License

This project is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). See LICENSE.

Contributing

Feedback, questions, and proposals are welcome via this repository's issue tracker.