Help MDZip grow

A minute or a month: there's a way to help at every size, and every one makes .mdz more useful for everyone.

Ways to help

From quickest to biggest. Pick whatever fits the time you have.

1 minute

Star and rate

If something here is useful to you, a star or an honest rating helps other people find it.

5 minutes

Tell someone

Mention MDZip where people ask how to send a Markdown document with its images, or share a page with someone who'd use it. Share Links has short addresses that are easy to paste.

10 minutes

Give feedback

Ideas, questions and "I tried it and…" stories go in Discussions. Found a bug? Report it in that app's own issues, such as MDZip Studio's issues, so it reaches the right place.

20 to 30 minutes

Test an app

Follow a short test script on your computer and post what worked and what didn't. No coding needed. Scripts cover MDZip Studio on a Mac and the Pandoc and MarkItDown converters. Intel Macs are especially welcome right now.

A weekend or more

Build something

Add .mdz to your app, or make a new one. It's free for any app, paid or in an app store.

Any size

Contribute code

Every MDZip repo is open source. Open an issue to say what you'd like to work on before a big change, so we can agree on the approach first.

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.

Statuses below last reviewed .

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 an included MCP server.
🖥️
Desktop app

MDZip Studio

A lightweight desktop Markdown editor with native .mdz support: standalone .md editing, folder packing, manifest editing, archive validation, and File Explorer integration.

Built on the same @mdzip/editor stack as the browser demo. Available now for Windows, macOS and Linux. Windows is also on WinGet as MDZip.Studio and Chocolatey as mdzip-studio, and macOS on Homebrew.
>_
CLI

mdz CLI

Create, inspect, and validate .mdz archives from the command line — cross-platform, with consistent conformance checks.

Repository: mdzip-project/mdzip-cli. Self-contained builds for Windows, macOS, and Linux; also on WinGet as MDZip.Cli.
🌐
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.
🪙
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.
Windows 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/iOS: first declare a Uniform Type Identifier (UTI) for .mdz in Info.plist so the system recognizes the file type at all, then a Quick Look generator plugin (macOS) or Quick Look extension (iOS, same framework, mobile target). Android: FileProvider + viewer activity. Linux: thumbnailer + file manager scripts.
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.

Built around the Obsidian plugin API and vault adapter for archive I/O. It opens .mdz files in Obsidian's own editor, keeps pasted images inside the archive, and adds archives to graph view and search.
📚
Libraries

Core libraries

Read, write and validate .mdz files from your own code. Every core passes the same shared conformance fixtures, so they agree on what a valid archive is.

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.

Built as a Pandoc custom reader and writer on the pure Lua core library. The writer packages assets referenced in the output.
In progress
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. Package 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 packages 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 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
📋
Standard

IANA MIME type registration

Formally register application/vnd.mdzip with IANA so the MIME type is recognized 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.

Adding .mdz to an existing app? Start with Add MDZip to your app: the libraries to use, tested code for opening, exporting and saving, and ready-made prompts for AI coding assistants.

Producer checklist

When creating an .mdz archive:

  1. Collect source Markdown and assets in a staging tree
  2. Normalize text encoding to UTF-8 for Markdown and JSON files
  3. Normalize line endings to LF in Markdown files and manifest.json; leave other files as they are
  4. Validate file paths against Section 5.4 constraints
  5. Write manifest.json with spec.version and entryPoint (plus title and mode), verify entryPoint names a Markdown file in the archive, and preserve unknown fields when rewriting an existing manifest
  6. When modifying an existing archive, confirm the entry point still resolves to the same file
  7. Report links that point outside the archive to the author as a notice; don't rewrite them
  8. 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; reject rather than rename
  3. Parse manifest.json if present; reject unsupported spec.version major versions; keep unknown fields; don't require a manifest
  4. Resolve the primary Markdown file via the entry point discovery algorithm: a missing or invalid entryPoint is an error, never a silent fallback; set aside support files such as README.md
  5. Parse Markdown with UTF-8 decoding; accept LF and CRLF
  6. Resolve relative links against the referencing file's path, matching paths exactly (case-sensitive); links that leave the archive stay unresolved unless supported within a trusted location
  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    # metadata and entry point (always written by tools)
|-- 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           // not a valid ZIP, or a compression method other than 0 or 8
ERR_ZIP_ENCRYPTED         // archive or entries use unsupported encryption
ERR_PATH_INVALID          // entry path violates Section 5.4 constraints
ERR_PATH_CONFLICT         // a file's path is also another entry's directory
ERR_DUPLICATE_PATH        // two entries with the same path after NFC normalization
ERR_MANIFEST_INVALID      // manifest.json is not JSON, or a critical field is invalid
ERR_ENTRYPOINT_UNRESOLVED // no unambiguous primary Markdown file found
ERR_ENTRYPOINT_INVALID    // entryPoint is not a valid Markdown file path
ERR_ENTRYPOINT_MISSING    // entryPoint names a file not in the archive
ERR_VERSION_UNSUPPORTED   // manifest spec.version major version not supported
ERR_MODE_UNSUPPORTED      // manifest mode is not supported or not recognized

Building with AI assistance

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

  • The exact target spec version (currently 1.2.1)
  • Whether you are implementing a producer, consumer, or both
  • Your required conformance scope (minimum MUSTs vs. SHOULDs included)
  • Required behavior for ambiguous entry points
  • Explicit test expectations from the spec's shared conformance fixtures

Useful libraries

Start with an MDZip core library if your language has one: it reads, writes and validates .mdz files and is tested against the spec's shared fixtures. The cores don't render Markdown, so you'll also want a renderer. In JavaScript you can skip both: the MDZip editor opens an .mdz and shows it, images included, as a read-only viewer or a full editor. For other languages, use a ZIP library and follow the conformance checklist; it lists the ZIP rules that catch most implementations out, such as libraries that always write ZIP64.

LanguageRead and write .mdzRender the Markdown
JavaScript / TypeScriptCore: @mdzip/core-jsViewer and editor: @mdzip/editor, or its Angular, React and Vue wrappers. Or your own renderer with the core: marked, markdown-it
.NETCore: MDZip.CoreMarkdig
RustCore: mdzip-corepulldown-cmark, comrak
PythonCore: mdzip-coremarkdown-it-py
LuaCore: mdzip-core-luaPandoc (Lua API), lunamark
Goarchive/zip (standard library)goldmark
Java / KotlinCore: org.mdzip:mdzip-corecommonmark-java
SwiftCore: mdzip-core-swiftswift-markdown
PHPZipArchive (built in)league/commonmark
Rubyrubyzipcommonmarker
C / C++libzipcmark-gfm

Missing your language? A core library for it is a good first project, and there's a ready-made prompt for having an AI assistant build one against the shared tests.

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.