The Problem
Plain Markdown files are portable. Real documents are usually not. As soon as images, diagrams, and supporting files are involved, sharing reliably across tools and teams becomes fragile.
What breaks in practice
- Markdown depends on external files that are easy to separate from the main document.
- Different tools use different image and attachment conventions.
- Wiki-style or tool-specific links often require custom resolution logic.
- Folder-based handoff has no standard contract for entry point, metadata, or validation.
How images are handled today
Tooling typically falls into three models. Each model is workable inside its own ecosystem, but interoperability costs increase when moving content between systems.
- Relative local files: explicit paths like
. - Managed media stores: platform-controlled upload locations and rewritten paths.
- Wiki or implicit references: non-standard references resolved by application rules.
| Platform | Primary model | Typical image reference |
|---|---|---|
| GitHub | Relative local files |  |
| Obsidian | Relative local + wiki references | ![[image.png]] and markdown paths |
| Ghost / CMS workflows | Managed media stores | Platform URL or configured media path |
| Wiki-oriented tools | Implicit references | Wiki/resource syntax |
How does .mdz compare?
Existing document formats solve adjacent problems but not the same combination of requirements: Markdown-native content, explicit packaged assets, easy inspection, and predictable structure.
| Property | DOCX | EPUB | Folder of .md |
.md in ZIP |
MDZip .mdz |
|
|---|---|---|---|---|---|---|
| Single file with dedicated extension | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Plain text internals | ❌ | 🟡 | 🟡 | ✅ | ✅ | ✅ |
| Markdown-native | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| Predictable contract for tools | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
✅ yes · ❌ no · 🟡 partial
For a deeper look at the closest relatives — TextBundle/TextPack, the independent Rust MDZ project, EPUB, and DOCX — see MDZip and Related Formats.
Solution requirements
A practical archive format for Markdown workflows should satisfy these constraints:
- Single-file handoff for transport and archiving.
- Stable entry-point discovery.
- Deterministic relative-path behavior for assets.
- Optional metadata with a defined schema.
- No lock-in to one editor or platform.
- Graceful fallback when dedicated tooling is unavailable.
These constraints are the basis for the MDZip format and the reason the specification defines explicit structure rather than relying on ad hoc ZIP conventions.
This page renders from the-problem.mdz — one self-contained file. Download it, open it in the web editor, or read how these pages are made.