MDZ packages (zipped Markdown)
An MDZ file (.mdz, MIME type application/x-mdz) is a ZIP archive that bundles a Markdown document with its images and other assets, so that a document stays a plain, open, human-readable format while remaining a single file.
Progressive Web Office implements the MDZ specification v1.1.0 published by the wflixu/mdz project (MIT), both as a reader and a writer.
Layout
document.mdz (ZIP archive)
├── index.md # main Markdown document (UTF-8, CommonMark + GFM)
├── manifest.json # metadata and asset list (required)
└── assets/
├── images/ # images referenced as ./assets/images/...
├── videos/
├── audio/
└── files/Manifest
{
"version": "1.1.0",
"title": "Document Title",
"author": "Ada Lovelace",
"date": "2026-10-01",
"filename": "index.md",
"assets": [
{
"id": "3fa1c2d4e5f60718",
"path": "assets/images/3fa1c2d4e5f60718.png",
"type": "image",
"alt": "A diagram"
}
]
}| Field | Type | Required | Notes |
|---|---|---|---|
version | string | yes | MDZ specification version; major version 1 is supported |
title | string | yes | Document title |
author | string | null | no | Author name |
date | string | null | no | ISO 8601 date recommended |
filename | string | null | no | Original Markdown file name |
assets | array | no | id, path, type required; alt, title optional |
subject | string | null | no | Subject (Progressive Web Office extension) |
description | string | null | no | Summary (extension) |
keywords | string[] | no | Keywords (extension; a comma-separated string is also read) |
language | string | null | no | BCP 47 language tag, e.g. fr (extension) |
license | string | null | no | Licence, preferably an SPDX identifier such as CC-BY-4.0 (extension) |
The document properties (ⓘ in the editor) are stored in the manifest; the index.md of a package written by Progressive Web Office has no front matter. When an index.md does have one, its values fill the fields the manifest leaves empty. The last five fields are proposed upstream to become part of the MDZ specification.
Unknown fields — including x-* extensions — are accepted and preserved when the package is saved again.
JSON Schema
The manifest is validated against a JSON Schema (draft 2020-12), published at schemas/mdz-manifest-1.schema.json:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://progressive-web-office.github.io/docs/schemas/mdz-manifest-1.schema.json",
"title": "MDZ manifest, version 1.x",
"description": "manifest.json of an MDZ package (ZIP archive with index.md, manifest.json and assets/), following the MDZ specification v1.1.0 by wflixu (https://github.com/wflixu/mdz). Unknown properties are allowed for forward compatibility; custom extensions should use 'x-' prefixed keys.",
"type": "object",
"required": [
"version",
"title"
],
"properties": {
"version": {
"description": "MDZ specification version (semantic version). This schema covers major version 1.",
"type": "string",
"pattern": "^1\\.(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?$"
},
"title": {
"description": "Document title (defaults to the file name).",
"type": "string"
},
"author": {
"description": "Document author name.",
"type": [
"string",
"null"
]
},
"date": {
"description": "Publication or creation date (ISO 8601 recommended).",
"type": [
"string",
"null"
]
},
"subject": {
"description": "Subject of the document (Progressive Web Office extension).",
"type": [
"string",
"null"
]
},
"description": {
"description": "Summary of the document (Progressive Web Office extension).",
"type": [
"string",
"null"
]
},
"keywords": {
"description": "Keywords (Progressive Web Office extension).",
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"description": "Language of the document as a BCP 47 tag, e.g. \"fr\" or \"en-GB\" (Progressive Web Office extension).",
"type": [
"string",
"null"
]
},
"license": {
"description": "Licence of the document, preferably an SPDX identifier such as \"CC-BY-4.0\" (Progressive Web Office extension).",
"type": [
"string",
"null"
]
},
"source": {
"description": "Where the document comes from: the address of its file in a repository or on a WebDAV server (Progressive Web Office extension).",
"type": [
"string",
"null"
]
},
"filename": {
"description": "Original Markdown file name (v1.1.0+).",
"type": [
"string",
"null"
]
},
"assets": {
"description": "Embedded assets.",
"type": "array",
"items": {
"$ref": "#/$defs/asset"
}
}
},
"additionalProperties": true,
"$defs": {
"relativePath": {
"description": "Archive-relative path: no leading slash, no backslash, no '..' segment.",
"type": "string",
"minLength": 1,
"pattern": "^(?![/\\\\])(?!.*\\\\)(?!(.*/)?\\.\\.(/|$)).+$"
},
"asset": {
"type": "object",
"required": [
"id",
"path",
"type"
],
"properties": {
"id": {
"description": "Unique identifier of the asset.",
"type": "string",
"minLength": 1
},
"path": {
"$ref": "#/$defs/relativePath"
},
"type": {
"description": "Asset category: image, video, audio, file, ...",
"type": "string",
"minLength": 1
},
"alt": {
"description": "Alternative text for images.",
"type": "string"
},
"title": {
"description": "Title or caption.",
"type": "string"
}
},
"additionalProperties": true
}
}
}The schema is a contribution of this project and is proposed upstream to wflixu/mdz.
How Progressive Web Office reads MDZ
- The manifest must be valid JSON and valid against the schema; the major version must be
1. Otherwise the package is refused with an explanation. index.mdis the document. Images referenced with relative links (./assets/images/...) are embedded in the editor.- Paths that are absolute, contain
..escaping the archive or backslashes are never resolved. - Assets that the editor does not display (videos, audio, other files) are kept and written back on save.
How it writes MDZ
index.mdis generated from the document (CommonMark + GFM tables).- Each distinct image is stored once as
assets/images/<content-hash>.<ext>and referenced as./assets/images/<content-hash>.<ext>. manifest.jsonis written withversion1.1.0and validated by the test-suite against the JSON Schema.
Turning a plain ZIP into an MDZ
Any ZIP archive containing Markdown files and images can be opened:
- If it contains a single
.mdfile, that file is the document. - If it contains several, you are asked which one is the entry point (
index.md, thenREADME.md, are pre-selected). - Relative image links are resolved inside the archive.
Choose Save (or Save as → Markdown package (.mdz)) to obtain a conforming .mdz: the manifest is generated, images move to assets/images/, and the other files (including other Markdown files) are kept under assets/files/, with links rewritten accordingly.