The MDZip project
MDZip is an open format project with a specification, core libraries, and reference tools. This page summarizes the implementation layout and repository map. For why the project exists and the principles behind it, see About MDZip.
All of it is built largely by AI agents, with one human, the architect, who is also the maintainer, reviewing the changes before they ship. See how MDZip itself is built. If the project stopped, your files would still open with any ZIP tool and text editor, and the open spec and libraries could be carried on by anyone: see Your files outlive us.
Project scope
- Define and maintain the MDZip format specification.
- Provide reusable core libraries for archive reading/writing and validation.
- Ship reference tools that exercise the spec in practical workflows.
- Keep behavior interoperable across platform and web ecosystems.
The ecosystem at a glance
| Layer | Available |
|---|---|
| Specification | |
| Core libraries | |
| Web editor | |
| IDE plugins | |
| Application plugins | |
| Apps | |
| Converters |
Dashed badges are in progress or coming soon. For what works with what, with status, see Works with MDZip.
Release status
Latest release and package status for MDZip repositories.
Specification
| GitHub Repo | Description | Release | Package |
|---|---|---|---|
| mdzip-spec | .mdz format specification. All other repos ultimately refer to this. |
— |
Core libraries
| GitHub Repo | Description | Release | Package |
|---|---|---|---|
| mdzip-core | Platform (OS/runtime) .mdz core library (C#/.NET). |
||
| mdzip-core-js | JavaScript .mdz core library (@mdzip/core-js, TypeScript, browser + Node.js). |
||
| mdzip-core-rust | Rust .mdz core library (mdzip-core crate, Rust 1.85+). |
||
| mdzip-core-python | Python .mdz core library (mdzip-core, standard library only, Python 3.10+). |
||
| mdzip-core-lua | Lua .mdz core library (mdzip-core-lua, pure Lua 5.3/5.4, no dependencies). |
||
| mdzip-core-swift | Swift .mdz core library (mdzip-core-swift, Swift 5.9+, iOS 15+, macOS 12+ and Linux, with Swift Package Manager). |
Swift Package Manager (from the Git tag) | |
| mdzip-core-kotlin | Kotlin .mdz core library (org.mdzip:mdzip-core, Android 5.0+ and Java 8+, usable from Java, no dependencies beyond the Kotlin standard library). |
App libraries
| GitHub Repo | Description | Release | Package |
|---|---|---|---|
| mdzip-editor | @mdzip/editor, framework-independent MDZip workspace engine and browser view. |
||
| mdzip-editor | @mdzip/editor-react, React wrapper for the MDZip workspace editor. |
||
| mdzip-editor | @mdzip/editor-vue, Vue wrapper for the MDZip workspace editor. |
||
| mdzip-editor | @mdzip/editor-ng, Angular UI components for the MDZip workspace engine. |
Applications & Extensions/Plugins
| GitHub Repo | Description | Release | Package |
|---|---|---|---|
| mdzip-cli | Platform (OS/runtime) CLI for create/extract (C#/.NET). | — | |
| mdzip-vscode | VS Code custom editor and included MCP server for reading and writing .mdz files, including packaged images. |
||
| mdzip-studio | Cross-platform desktop/web application for MDZip authoring and management. The Windows install adds a File Explorer shell extension with .mdz preview and registration. |
||
| mdzip-google-voice-exporter | Userscript — exports a Google Voice conversation to .mdz. |
— | |
| mdzip-obsidian | Obsidian plugin — open and edit .mdz files in a vault with Obsidian's own editor, follow links into and out of archives, and see archives in graph view and search. |
||
| mdzip-markitdown | MarkItDown plugin — converts .mdz to Markdown, and its markitdown-mdz command converts Word, PowerPoint and HTML to .mdz with the images kept. |
In progress | — |
| mdzip-pandoc | Pandoc reader and writer — converts .mdz to and from Word, EPUB, HTML and more. |
In progress | — |
Architecture and dependency flow
The project separates format definition, reusable core logic, and end-user tools.
Current state
- Specification exists and is publicly versioned.
- Seven core libraries are available, and all pass the specification's shared fixtures:
MDZip.Core(C#/.NET) and@mdzip/core-js(TypeScript), for platform and web runtimes, plusmdzip-corefor Rust,mdzip-corefor Python (standard library only),mdzip-core-luafor Lua (pure Lua),org.mdzip:mdzip-corefor Kotlin and Java (Android and the JVM) andmdzip-core-swiftfor Swift (iOS, macOS and Linux). - A Pandoc reader and writer built on the Lua core, and a MarkItDown plugin built on the Python core, are in progress.
mdzip-cliis available as the cross-platform reference CLI.- The MDZip editor library is now published as a family of scoped packages under the
@mdzipnpm organization:@mdzip/editor(framework-independent engine),@mdzip/editor-react,@mdzip/editor-vue, and@mdzip/editor-ng. mdzip-vscodeis available on the VS Code Marketplace and on Open VSX (for VSCodium, Cursor and similar) as "MDZip Editor" (more about it) and supports packaged images plus included MCP workflows.- The Obsidian plugin is available in Obsidian's Community plugins, for desktop and mobile. It opens
.mdzfiles in Obsidian's own editor, keeps pasted images inside the archive, follows links into and out of archives, and adds archives to graph view and search. - This site's browser viewer and packager demos use
@mdzip/core-jsfor shared archive behavior. - The Studio page preview is rendered by the published
@mdzip/editorlibrary itself, so it exercises the real editor — including progressive image hydration — rather than a static mockup. - MDZip Studio is available for Windows (installer, portable
.exe, WinGet or Chocolatey), macOS (.dmgor Homebrew) and Linux as a desktop Markdown editor with native.mdzsupport, standalone.mdediting, folder packing, manifest editing, archive validation, manual and background update checks, and file-type registration (plus a File Explorer preview on Windows).