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. A VS Code extension and the MDZip Studio desktop app are already live; the remaining projects below 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 live in MDZip Studio
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.

Repository: mdzip-project/mdzip-vscode. Built as a VS Code custom editor with packaged image support and a bundled MCP server.
Live on Marketplace
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.

Plugin work has started, but it is not public yet. Built around the Obsidian plugin API and vault adapter for archive I/O.
Started, not public
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
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 editor demo

A browser editor that accepts .mdz and .md files via drag-and-drop and renders them with full entry-point navigation, image display, and multi-file sidebar — no server, no upload. Also the reference integration of @mdzip/editor.

The editor component is published as @mdzip/editor on npm. The demo is an open-source Vite app showing a complete integration.
Live at MDZip.org/editor-demo.html
🪙
Web framework

Angular, Vue & React packages

Embed the MDZip workspace editor natively in your app using the official framework packages — drop-in components with full TypeScript support for Angular, Vue, and React.

Live on npm
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.

Published as an open project with SVG source, usage guidelines, and a license — free to use in app icons, documentation, and tooling.
Available on GitHub
📋
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

Recommended archive layout

A typical .mdz archive keeps content and assets organized like this:

document.mdz/
|-- index.md         # recommended entry point
|-- manifest.json    # optional metadata
|-- chapter.md       # additional markdown files
|-- assets/          # images, styles, media
    |-- images/
    |-- styles/

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.

Read the Specification Share a Project Idea