Ecosystem

Use cases & future tools

Who benefits from .mdz, how they use it today, and what the community could build next.

Use Cases

What is .mdz good for?

Anywhere you'd reach for a Word doc, a wiki page, or a folder of Markdown files — but you want something open, portable, and readable without installing anything.

🎁

Wiki in a box

Multiple linked Markdown pages, images, and navigation — all in one file. Send it over email or Slack. The recipient doesn't need a wiki account, a server, or a cloned repo.

📄

The document that outlives its software

Formatted text, headings, images, tables — the things people actually reach for Word to produce — stored as plain Markdown in an open archive. No proprietary binary, no software subscription required to read it in ten years.

🧳

The README that travels

Detach your project docs from GitHub. Bundle the README, architecture diagrams, and screenshots into a .mdz that tells the full story without a browser or an internet connection.

📧

A folder that fits in an email

Stop attaching a ZIP and explaining what to do with it. A .mdz is self-describing — any recipient can rename it to .zip, extract, and read. No instructions needed.

🔀

The diff-able document

Unlike DOCX or PDF, a .mdz lives happily in git. Track every change to your documentation, run code review on prose, and roll back like you would with source code.

📖

An ebook you actually own

EPUB is ZIP-based too, but locked to specific readers and XML internals. A .mdz is plain Markdown — readable in any editor, convertible with Pandoc once extracted, zero proprietary baggage. Native Pandoc support is a future project.

🎓

Course materials, no login required

Lesson notes, exercise sheets, and images in one file. Students open it with whatever tools they already have — no LMS, no platform account, no expiring link.

🚀

The manual that ships with the product

Publish a versioned .mdz alongside every software release. The docs for v1.2.0 are always exactly right for v1.2.0 — no wiki drift, no stale hosted pages.

📸

Meeting notes that keep their screenshots

Paste in the architecture diagram, the mockup, the whiteboard photo. Send one file. No Confluence, no Notion share link, no "the image didn't come through."

Future Projects

What the ecosystem could build

The spec is open. These are the tools that would make .mdz a first-class citizen across the Markdown ecosystem — and the most natural starting points for anyone who wants to contribute.

macOS/iOS Android Linux
OS integration

Native file preview

See rendered .mdz content without extracting — on any platform, from the Files app on iPhone to the preview pane in File Explorer.

Windows: IPreviewHandler shell extension. macOS: Quick Look generator plugin. iOS: Quick Look extension (same framework, mobile target). Android: FileProvider + viewer activity. Linux: thumbnailer + file manager scripts.
Not started
VS Code
Editor extension

VS Code extension

Open a .mdz file directly in VS Code: browse entries in the explorer, render the document in the preview pane, and save edits back into the archive.

Starting point: VS Code virtual file system API + existing Markdown preview extension.
Not started
Obsidian
Editor extension

Obsidian plugin

Import a .mdz archive into a vault in one click, or export any note (with its attachments) as a .mdz for sharing outside Obsidian.

Starting point: Obsidian plugin API, app.vault.adapter for ZIP I/O.
Not started
🛠️
CLI tool

mdz CLI

A command-line tool for creating, extracting, validating, and inspecting .mdz files — with subcommands like mdz create, mdz validate, and mdz ls.

Could be a single portable binary in Go, Rust, or .NET, or a Node.js package for the JS ecosystem.
Not started
Pandoc
Pandoc

Pandoc reader/writer

A Pandoc custom reader and writer for .mdz, enabling conversion to/from HTML, EPUB, PDF, DOCX, and any other format Pandoc supports.

Starting point: Pandoc Lua filter or custom reader API. The writer would bundle assets referenced in the output.
Not started
GitHub
CI/CD

GitHub Action

A GitHub Action that packages a repository's documentation into a .mdz artifact on every release, making versioned doc bundles part of every release workflow.

Could wrap the CLI tool — a thin action YAML calling mdz create and uploading the artifact.
Not started
Typora
Editor extension

Typora support

Native open/save support in Typora so authors never have to think about the ZIP layer — just open a .mdz like any other file.

Typora is an Electron app; file format plugins are achievable without upstream changes.
Not started
Editor integration

More editors worth targeting

Several Markdown editors already handle multi-file vaults or rich document workflows — natural fits for .mdz import/export support.

  • Zettlr Zettlr — academic writing focus, already exports to multiple formats via Pandoc
  • Markdown Monster Markdown Monster — Windows editor with a rich plugin API and existing ZIP-file handling
  • Joplin Joplin — open-source notes app with import/export extensions and an established plugin ecosystem
  • Mark Text Mark Text — minimal Electron editor; open source and actively maintained
Not started
📱
Mobile

Mobile editors worth targeting

Several iOS and Android Markdown editors already handle file import/export workflows — natural candidates for .mdz open/save support.

  • iA Writer iA Writer — iOS/Android/desktop; strong file import/export and URL scheme support
  • Drafts Drafts — iOS; highly extensible with actions, ideal for import/export workflows
  • GitJournal GitJournal — iOS/Android; git-based Markdown notes with file-level operations
Not started
🌐
Web

Browser-based viewer

A static web app that accepts a .mdz file via drag-and-drop and renders it in the browser — entry point navigation, image display, and all — with no server required.

Starting point: JSZip + a client-side Markdown renderer like marked or markdown-it. Entirely static HTML/JS.
Not started
🎨
Brand

A mark for .mdz

A canonical, freely usable visual mark for the .mdz format — for use in app icons, documentation, and tooling. Similar to markdown-mark for Markdown itself.

Would ideally include SVG source, usage guidelines, and a clear open license. A recognised mark helps tools signal .mdz support at a glance.
Not started
📋
Standard

IANA MIME type registration

Formally register application/vnd.markdownzip with IANA so the MIME type is recognised by browsers, mail clients, and operating systems without per-app configuration.

Requires an RFC-style registration document submitted to IANA. The spec already defines the type.
Not started
Resources

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.

Producer checklist

When creating a .mdz archive:

  1. Collect source Markdown and assets in a staging tree
  2. Normalize text encoding to UTF-8
  3. Normalize line endings to LF where practical
  4. Validate file paths against Section 5.4 constraints
  5. If manifest.json is present — verify required fields (mdz, title); verify entryPoint exists; preserve unknown fields when round-tripping
  6. Ensure at least one unambiguous entry point condition is satisfied
  7. Create an unencrypted ZIP archive with the .mdz extension

Consumer checklist

When opening a .mdz archive:

  1. Open as ZIP and reject encrypted/password-protected entries
  2. Enumerate entries and validate path safety constraints
  3. Parse manifest.json if present, ignoring unknown fields
  4. Resolve the primary Markdown file via the entry point discovery algorithm
  5. Parse Markdown with UTF-8 decoding; accept LF and CRLF
  6. Resolve relative links against the referencing file's path; reject any path that escapes the archive root
  7. If no unambiguous entry point exists, show an explicit error or user choice — do not silently auto-pick

Suggested error constants

Standardised error identifiers make cross-tool debugging easier:

Error categoriesConstants
ERR_ZIP_INVALID          // archive is not a valid ZIP container
ERR_ZIP_ENCRYPTED        // archive or entries use unsupported encryption
ERR_PATH_INVALID         // entry path violates Section 5.4 constraints
ERR_MANIFEST_INVALID     // manifest.json is malformed or missing required fields
ERR_ENTRYPOINT_UNRESOLVED // no unambiguous primary Markdown file found
ERR_ENTRYPOINT_MISSING   // entryPoint references a file not in the archive
ERR_VERSION_UNSUPPORTED  // manifest mdz major version not supported

Building with AI assistance

The spec includes guidance for AI-assisted implementation. For best results, include in your prompt:

Useful libraries

These existing open-source libraries cover the heavy lifting for most .mdz implementations:

Want to build something?

The specification is open and the ecosystem is wide open. Read the spec, pick a project, and get in touch. We're also looking for someone to create a canonical visual mark for .mdz — like markdown-mark for Markdown.

Read the Specification Join the Discussion