Build the MDZip ecosystem

Pick a project, start a repo, and help make .mdz a first-class format across tools and platforms.

Roadmap

Project ideas

The spec is open. Beyond the tools already underway, these projects would make .mdz a first-class citizen across the Markdown ecosystem. Pick one to run with, host it in your own repo, or open a discussion to collaborate with me or others. The spec is your contract; the community is your support network; and the ecosystem is your playground. Let's build something great together.

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.
Windows previewer in progress
VS Code
Editor extension

VS Code extension

Open an .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

Open an .mdz archive in a vault just like it's a folder, or export any note (with its attachments) as an .mdz for sharing outside Obsidian.

Starting point: Obsidian plugin API, app.vault.adapter for ZIP I/O.
Not started
Bear
Editor extension

Bear support

Import and export .mdz bundles so Bear notes can travel with their attachments and backlinks intact.

Starting point: Bear already handles bundled Markdown formats; an .mdz importer/exporter would fit naturally.
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
MkDocs
Static site

MkDocs plugin for .mdz

Add native .mdz import/export support for MkDocs projects — including mkdocs.yml, docs, and assets — for portable sharing or archival.

Starting point: MkDocs plugin API. Bundle mkdocs.yml, docs/, and any theme overrides into the archive.
Not started
GitHub
CI/CD

GitHub Action

A GitHub Action that packages a repository's documentation into an .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 (depends on CLI)
Typora
Editor extension

Typora support

Native open/save support in Typora so authors never have to think about the ZIP layer — just open an .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 an .mdz file via drag-and-drop and renders it in the browser — entry point navigation, image display, and all — with no server required. Maybe build re-usable JS or TS components for integration into other projects.

Built with JSZip + marked. Entirely static HTML/JS — no server, no upload.
Live at MDZip.org/viewer.html
🪙
Web framework

Angular/React/Vue wrappers

Package the .mdz viewer as framework components so teams can embed it directly inside web apps and internal tools.

  • Angular Angular — a component wrapping the viewer with drop-in templates and inputs
  • React React — a component + hooks API for loading and rendering archives
  • Vue Vue — a component and composable for easy integration
Not started
MDZip logo concept
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.

Current mark shown here is a first-cut concept. Final direction should include SVG source, usage guidelines, and a clear open license.
Not started
📋
Standard

IANA MIME type registration

Formally register application/vnd.MDZip 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 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 an .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 — validate JSON, ensure spec.version is present when the manifest is producer-generated, and verify entryPoint exists if set; 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 an .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; validate JSON and honor spec.version when present; ignore unknown fields
  4. Resolve the primary Markdown file via the entry point discovery algorithm; reject unsupported mdz major versions
  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:

Ready to start a project?

Pick a target from the roadmap, create a repo, and use the spec as your contract. If you want feedback or collaboration, open a discussion and share your plan. We also need a canonical visual mark for .mdz — like markdown-mark for Markdown.

Read the Specification Share a Project Idea