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 SPEC.md Fixtures Examples
Core libraries .NET JavaScript/TypeScript Rust Python Lua Swift Kotlin
Web editor JavaScript/TypeScript Angular React Vue
IDE plugins VS Code VSCodium Cursor Antigravity
Application plugins Obsidian
Apps MDZip Studio, Windows, macOS, Linux Explorer preview, Windows mdz CLI, Windows, macOS, Linux Web editor
Converters Google Voice MarkItDown, in progress Pandoc, in progress

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. Latest release for mdzip-spec —

Core libraries

GitHub Repo Description Release Package
mdzip-core Platform (OS/runtime) .mdz core library (C#/.NET). Latest release for mdzip-core NuGet package version for MDZip.Core
mdzip-core-js JavaScript .mdz core library (@mdzip/core-js, TypeScript, browser + Node.js). Latest release for mdzip-core-js NPM package version for @mdzip/core-js
mdzip-core-rust Rust .mdz core library (mdzip-core crate, Rust 1.85+). Latest release for mdzip-core-rust crates.io version for mdzip-core
mdzip-core-python Python .mdz core library (mdzip-core, standard library only, Python 3.10+). Latest release for mdzip-core-python PyPI version for mdzip-core
mdzip-core-lua Lua .mdz core library (mdzip-core-lua, pure Lua 5.3/5.4, no dependencies). Latest release for mdzip-core-lua LuaRocks version for mdzip-core-lua
mdzip-core-swift Swift .mdz core library (mdzip-core-swift, Swift 5.9+, iOS 15+, macOS 12+ and Linux, with Swift Package Manager). Latest release for mdzip-core-swift 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). Latest release for mdzip-core-kotlin Maven Central version for org.mdzip:mdzip-core

App libraries

GitHub Repo Description Release Package
mdzip-editor @mdzip/editor, framework-independent MDZip workspace engine and browser view. Latest release for mdzip-editor NPM package version for @mdzip/editor
mdzip-editor @mdzip/editor-react, React wrapper for the MDZip workspace editor. Latest release for mdzip-editor NPM package version for @mdzip/editor-react
mdzip-editor @mdzip/editor-vue, Vue wrapper for the MDZip workspace editor. Latest release for mdzip-editor NPM package version for @mdzip/editor-vue
mdzip-editor @mdzip/editor-ng, Angular UI components for the MDZip workspace engine. Latest release for mdzip-editor NPM package version for @mdzip/editor-ng

Applications & Extensions/Plugins

GitHub Repo Description Release Package
mdzip-cli Platform (OS/runtime) CLI for create/extract (C#/.NET). Latest release for mdzip-cli —
mdzip-vscode VS Code custom editor and included MCP server for reading and writing .mdz files, including packaged images. Latest release for mdzip-vscode MDZip on the VS Code Marketplace MDZip on Open VSX
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. Latest release for mdzip-studio Download for Windows Download for macOS Download for Linux
mdzip-google-voice-exporter Userscript — exports a Google Voice conversation to .mdz. Latest release for mdzip-google-voice-exporter —
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. Latest release for mdzip-obsidian MDZip for Obsidian, in Community plugins
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, plus mdzip-core for Rust, mdzip-core for Python (standard library only), mdzip-core-lua for Lua (pure Lua), org.mdzip:mdzip-core for Kotlin and Java (Android and the JVM) and mdzip-core-swift for 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-cli is available as the cross-platform reference CLI.
  • The MDZip editor library is now published as a family of scoped packages under the @mdzip npm organization: @mdzip/editor (framework-independent engine), @mdzip/editor-react, @mdzip/editor-vue, and @mdzip/editor-ng.
  • mdzip-vscode is 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 .mdz files 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-js for shared archive behavior.
  • The Studio page preview is rendered by the published @mdzip/editor library 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 (.dmg or Homebrew) and Linux as a desktop Markdown editor with native .mdz support, standalone .md editing, folder packing, manifest editing, archive validation, manual and background update checks, and file-type registration (plus a File Explorer preview on Windows).