# 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.html): 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/docs/getting-started.html): Open, create, and validate your first .mdz — with Studio, VS Code, the browser tools, or the CLI.
- [Using the mdz CLI](https://mdzip.org/docs/cli.html): Create, inspect, validate, and edit .mdz archives from the command line: install, command tour, and scripting notes.
- [Editor Developer Guide](https://mdzip.org/docs/editor-developer-guide.html): Embed the @mdzip/editor workspace in web or desktop apps: packages, API, control policies, events, and the framework wrappers.
- [Editor Theming](https://mdzip.org/docs/editor-theming.html): Theming the @mdzip/editor component: color schemes, CSS variables, and integrating with a host application look.
- [JavaScript](https://mdzip.org/docs/editor-js.html): The @mdzip/editor package for vanilla JavaScript/TypeScript: install, mount the workspace view, and configure it.
- [Angular](https://mdzip.org/docs/editor-angular.html): The @mdzip/editor-ng wrapper: use the MDZip workspace editor as an Angular component.
- [React](https://mdzip.org/docs/editor-react.html): The @mdzip/editor-react wrapper: use the MDZip workspace editor as a React component.
- [Vue](https://mdzip.org/docs/editor-vue.html): The @mdzip/editor-vue wrapper: use the MDZip workspace editor as a Vue component.
- [AI Producer Guide](https://mdzip.org/docs/ai.html): How AI assistants and automated tools create valid .mdz archives: minimal archive, manifest, entry-point rules, common mistakes, validation.
- [Example Archives](https://mdzip.org/docs/examples.html): Canonical, validating .mdz examples: minimal, with images, and multi-document project mode — templates for producers and fixtures for implementers.
- [MDZip and Related Formats](https://mdzip.org/docs/related-formats.html): How .mdz relates to TextBundle/TextPack, EPUB, and DOCX — acknowledged prior work, a comparison table, and the interoperability stance.

## Example archives

- [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
- [Tools](https://mdzip.org/tools.html): apps and developer libraries
- [FAQ](https://mdzip.org/faq.html): frequently anticipated questions
- [Browser warnings on .mdz](https://mdzip.org/mdz-warnings.html): the legacy extension collision, explained