MDZip Documentation
Guides and references for the MDZip format and tools.
Using MDZip
Getting Started with MDZip
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
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
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
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
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
Editor Developer Guide
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
Theme the @mdzip/editor component: light and dark color schemes, custom themes, the CSS variable reference, theme constants, multiple editors, accessibility.
JavaScript
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
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
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
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.
Integration and reference
Add MDZip to Your App
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
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
How AI assistants and automated tools should create valid .mdz archives: the minimal archive, manifest, entry-point rules, assets, mistakes, and validation.
Example Archives
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
How .mdz compares to TextBundle/TextPack, EPUB, DOCX, and the separate Rust MDZ project: prior work, a comparison table, and the interoperability stance.