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, it can be named anything).
manifest.json is optional.
Assets should be organised 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.

Recommended structures

For a single-document archive:

document.mdz (ZIP archive)
├── index.md               # Recommended: conventional entry point
├── manifest.json          # Optional: metadata and entry-point override
├── README.md              # Optional: human-facing usage notes
├── 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
├── 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
└── 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	Optional structured metadata about the document package.
`README.md`	No	Optional human-facing guide for recipients without `.mdz` tooling.
`images/`, `styles/`, etc.	No	Type-named asset folders at the archive root (recommended convention).

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 is optional and lives at the archive root. Think of it as extra context for tools: title, entry point, authoring details, and document metadata.

You can keep this file minimal. For hand-authored archives, no fields are strictly required. If a conforming producer tool generates the manifest, it must include spec.version.

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.

Field	Required	Type	Notes
`spec.version`	Conditionally required	String	Required when `manifest.json` is emitted by a conforming producer; semver string.
`title`	No	String	Display title of the document package; if omitted, consumers should derive a title from context.
`mode`	No	String	Interpretation mode: `"document"` (default) or `"project"`. See Mode below.
`entryPoint`	No	String	Primary file path to open first (for non-default entry names).
`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.1.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:

If manifest.json specifies entryPoint and the file exists, open that file.
Otherwise, if index.md exists at the archive root, open it.
Otherwise, if there is exactly one root-level Markdown file, open it.
Otherwise, treat the entry point as unresolved and surface an explicit error or user choice.

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.1.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. Any path that would resolve outside the archive root (via ../ traversal) must be rejected.

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 any archive entry or link whose resolved path falls outside the archive root.
Prohibited characters — sanitize paths containing null bytes, control characters, or OS-reserved characters before filesystem extraction.
ZIP bombs — enforce reasonable limits on entry count, total uncompressed size, and compression ratio.
External URLs — warn users before following links to external resources embedded in document content.
Sensitive data — producers should not package credentials, private keys, or other sensitive data inside an archive.

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