# MDZip > A portable, cross-platform, AI-friendly file format and ecosystem for > packaging Markdown, images, and metadata into a single archive (.mdz). ## Specification - [MDZip Specification](https://mdzip.org/spec): the normative format specification - [Specification (raw Markdown)](https://raw.githubusercontent.com/mdzip-project/mdzip-spec/main/SPEC.md): same content, machine-friendly - [Manifest schema](https://github.com/mdzip-project/mdzip-spec/tree/main/schema): JSON schema for manifest.json ## Docs - [Getting Started with MDZip](https://mdzip.org/start): Open, create, and validate your first .mdz file with MDZip Studio, VS Code, the browser tools, or the mdz CLI, then see what's inside and how it opens. - [Refine a user story with AI](https://mdzip.org/docs/refine-a-story-with-ai.html): Bring an Azure DevOps or GitHub story into an .mdz, refine it with an AI assistant in VS Code through two MCP servers, and send the result back to the tracker. - [Using MDZip with Git, GitHub and Azure DevOps](https://mdzip.org/docs/git.html): Use MDZip (.mdz) files in Git, GitHub and Azure DevOps: keep Markdown as the source, read diffs with mdz textconv, and check and package them in CI pipelines. - [Using the mdz CLI](https://mdzip.org/docs/cli.html): Create, inspect, validate, and edit .mdz archives from the command line with the mdz CLI: installing it, a tour of the commands, extraction, and scripting. - [Encrypting .mdz Files](https://mdzip.org/docs/encryption.html): How to password-protect an .mdz file and keep it valid: encrypt the whole file with 7-Zip or age, or seal it in an envelope that explains how to open it. - [Editor Developer Guide](https://mdzip.org/docs/editor-developer-guide.html): Embed the @mdzip/editor workspace in web or desktop apps: packages, modes and controls, the browser API, preview lifecycle, links, toolbars, and wrappers. - [Editor Theming](https://mdzip.org/docs/editor-theming.html): Theme the @mdzip/editor component: light and dark color schemes, custom themes, the CSS variable reference, theme constants, multiple editors, accessibility. - [JavaScript](https://mdzip.org/docs/editor-js.html): Use @mdzip/editor in plain JavaScript or TypeScript: install it, mount the workspace view, and set the editor mode, control presets, density, and file handling. - [Angular](https://mdzip.org/docs/editor-angular.html): Use the MDZip workspace editor as an Angular component with @mdzip/editor-ng: install it, bind inputs and outputs, show archive diffs, and handle files. - [React](https://mdzip.org/docs/editor-react.html): Use the MDZip workspace editor as a React component with @mdzip/editor-react: install it, set props and callbacks, show diffs, and use the imperative API. - [Vue](https://mdzip.org/docs/editor-vue.html): Use the MDZip workspace editor as a Vue component with @mdzip/editor-vue: install it, bind props and events, show archive diffs, and handle images and files. - [Add MDZip to Your App](https://mdzip.org/docs/integrate.html): How to add .mdz support to your Markdown editor or note app, step by step: libraries for JavaScript and .NET, tested code for opening, exporting and saving, and ready-made prompts for AI coding assistants. - [Conformance Guide](https://mdzip.org/docs/conformance.html): What MDZip 1.2.0 requires of apps that open, create or save .mdz files, and what is optional: checklists, sample files, tests, and how to get your app listed. - [AI Producer Guide](https://mdzip.org/docs/ai.html): How AI assistants and automated tools should create valid .mdz archives: the minimal archive, manifest, entry-point rules, assets, mistakes, and validation. - [Example Archives](https://mdzip.org/docs/examples.html): Example .mdz archives that pass validation: a minimal file, one with images, and a multi-document project, as templates for producers and implementer fixtures. - [MDZip and Related Formats](https://mdzip.org/docs/related-formats.html): How .mdz compares to TextBundle/TextPack, EPUB, DOCX, and the separate Rust MDZ project: prior work, a comparison table, and the interoperability stance. ## News - [What's New](https://mdzip.org/news/index.html): every post; RSS at https://mdzip.org/feed.xml - [MDZip Studio is now on Mac](https://mdzip.org/news/2026-11-10-mdzip-studio-is-now-on-mac.html) (2026-11-10): MDZip Studio 1.7.0 runs on macOS: one download for Apple Silicon and Intel Macs, also on Homebrew. Double-click an .mdz in Finder to open it. - [MDZip on mobile: libraries for Android and iOS](https://mdzip.org/news/2026-11-07-mdzip-on-mobile-libraries-for-android-and-ios.html) (2026-11-07): Two new MDZip core libraries bring .mdz to phones: org.mdzip:mdzip-core for Android (Kotlin and Java) and mdzip-core-swift for iOS (Swift). Both pass the same shared conformance tests as the other MDZip libraries. - [Lua library for MDZip: pure Lua, no dependencies](https://mdzip.org/news/2026-11-06-lua-library-for-mdzip-pure-lua-no-dependencies.html) (2026-11-06): mdzip-core-lua is out on LuaRocks: read, write and validate .mdz files in pure Lua 5.3 or 5.4, with no C modules and no dependencies. It passes the same shared conformance tests as the other four MDZip core libraries. - [Google Voice exporter is now on Greasy Fork and OpenUserJS](https://mdzip.org/news/2026-11-03-google-voice-exporter-is-now-on-greasy-fork-and.html) (2026-11-03): The Google Voice exporter is on Greasy Fork and OpenUserJS: one-click install, automatic updates. It saves a Google Voice conversation, with its photos, as one .mdz file. - [MDZip for Obsidian is in Community plugins: keep notes and their images in one file](https://mdzip.org/news/2026-10-27-mdzip-for-obsidian-is-in-community-plugins-keep.html) (2026-10-27): The MDZip plugin is now in Obsidian's Community plugins, for desktop and mobile. Open and edit .mdz files in Obsidian's own editor, keep pasted images inside the file, and search, link and graph across archives and your notes. - [Python and Rust libraries for MDZip: four core libraries, one format](https://mdzip.org/news/2026-10-26-python-and-rust-libraries-for-mdzip-four-core.html) (2026-10-26): mdzip-core is out for Python (PyPI) and Rust (crates.io). Like the .NET and JavaScript libraries, both pass the specification's shared conformance tests, so every app using them reads and writes the same .mdz files. - [VS Code extension 1.7: now on Open VSX with improved MCP functionality](https://mdzip.org/news/2026-10-23-vs-code-extension-1-7-now-on-open-vsx-and-ai.html) (2026-10-23): MDZip for VS Code 1.7 is on Open VSX for VSCodium, Cursor and other editors built on VS Code. AI agents can now add, replace and remove any file in an .mdz. - [Spec 1.2.0 and new releases across the tools](https://mdzip.org/news/2026-10-21-spec-1-2-0-and-new-releases-across-the-tools.html) (2026-10-21): Version 1.2.0 of the MDZip specification is out, and the apps and libraries that read and write .mdz files have new releases that follow it. Archives… - [Announcing MDZip (.mdz) — a portable Markdown bundle format](https://mdzip.org/news/2026-03-09-announcing-mdzip-mdz-a-portable-markdown-bundle.html) (2026-03-09): I'm sharing the first draft of a new open file format spec: MDZip (.mdz). ## Example archives - [encrypted-envelope.mdz](https://mdzip.org/examples/encrypted-envelope.mdz): canonical validating .mdz example - [minimal.mdz](https://mdzip.org/examples/minimal.mdz): canonical validating .mdz example - [project.mdz](https://mdzip.org/examples/project.mdz): canonical validating .mdz example - [with-images.mdz](https://mdzip.org/examples/with-images.mdz): canonical validating .mdz example ## Key pages - [The file format](https://mdzip.org/format.html): how .mdz works - [What AI-friendly means](https://mdzip.org/ai.html): the eight properties behind the claim, and how AI assistants should handle an .mdz - [Project](https://mdzip.org/project.html): architecture diagram, repositories and release status - [Tools](https://mdzip.org/tools.html): apps and developer libraries - [Share links](https://mdzip.org/share-links.html): find and copy stable URLs for posts, email and bookmarks - [Core libraries](https://mdzip.org/core-libraries): compare .NET, JavaScript/TypeScript, Python, Rust and Lua; installation and first-read examples - [Works with MDZip](https://mdzip.org/apps): what MDZip works with, with status. Available today: Windows; Linux; macOS; Web browsers; Command line; ZIP tools; VS Code; VSCodium, Cursor and other editors built on VS Code; AI agents; Obsidian; Google Voice; JavaScript and TypeScript; .NET; Rust; React, Vue and Angular; Python; Lua; Swift; Kotlin and Java. In progress or coming soon: Word, PowerPoint and HTML files; Pandoc - [Ecosystem registry (JSON)](https://mdzip.org/ecosystem.json): every MDZip product by layer (specification, libraries, editors, plugins, apps, converters), with status, link and badge - [VS Code extension](https://mdzip.org/vscode): edit .mdz in VS Code; bundled MCP server for AI agents - [Obsidian plugin](https://mdzip.org/obsidian): edit .mdz in Obsidian; archives in graph view and search - [Google Voice exporter](https://mdzip.org/google-voice): browser userscript that saves a Google Voice conversation, with its photos, as one .mdz - [Browser editor demo](https://mdzip.org/editor-demo.html): in-browser .mdz viewer and editor demo - [Web packager](https://mdzip.org/packager.html): browser-based folder-to-.mdz packager - [Contribute](https://mdzip.org/contribute.html): project map, implementation guidance, and extension ideas - [FAQ](https://mdzip.org/faq.html): frequently anticipated questions - [Browser warnings on .mdz](https://mdzip.org/mdz-warnings.html): the legacy extension collision, explained