Download this page as .mdz

About MDZip

Mission

A Markdown document with pictures isn't one file. It's a text file and a folder of images, and they rarely stay together. Several apps have built their own way around this, and each works well inside the app that made it. The goal of the MDZip project is one shared, open format that any app can read and write, so a document isn't tied to the app it was written in.

The heart of the project is the specification. Everything else (the core libraries, MDZip Studio, the editor, the plugins, this website) exists to support the spec: to prove it works and to make it easy to adopt. MDZip isn't trying to be the app you use. It's trying to make sure whatever app you use can open your files. When a tool and the spec disagree, the tool gets fixed. Many formats grew the other way, with a tool first and a spec written later to describe what it happened to do. Markdown itself is the best-known example: it began as one script, and years of incompatible "flavors" followed before CommonMark set out to pin it down. MDZip starts from the spec so that doesn't happen again.

That's also why everything is open. The spec is CC BY 4.0, the code is Apache 2.0 and free for any app, paid ones included, and the .mdz mark is public domain. If you've already built a format like this, we'd rather work with you than compete: tell us what MDZip is missing.

Principles

Spec first

The specification is the product. The tools serve it, and when they disagree, the tool gets fixed. Every core library is tested against the same shared fixtures, so they agree on what a valid file is.

Open source first

When choosing which apps to bring MDZip to next, the project favors apps that are free, open source and available everywhere: Windows, Mac and Linux, and best of all on phones or the web as well. Paid apps, closed ones and apps for a single platform rank lower, or are left for other developers to build, with the libraries free to use. Within that, what counts most is how many people use an app and how fully it could support .mdz: opening and editing the file in place beats importing and exporting it. Apps that keep your notes as files on disk come before apps that keep them in a database. Closed apps aren't ruled out when they score well anyway, as the Obsidian plugin shows.

MDZip itself is open source too: the spec, the libraries, the apps and this website. Anyone can use them, fork them or build on them, including in paid apps.

No gatekeepers

MDZip goes first where nobody has to say yes: apps where a plugin or extension can add .mdz support without asking the app's makers. Where only the makers can add it, MDZip asks them, and keeps building elsewhere instead of waiting.

It also avoids gatekeepers that require payment. MDZip is a one-person open-source project, built in my spare time with limited resources, so it doesn't buy its way into app stores, developer programs or signing certificates. When the choice is between paying a gatekeeper and asking you to take one extra step, MDZip takes the extra step and explains it clearly. That's why Studio asks Mac users to click Open Anyway the first time they open it.

The same goes for you. You don't need permission, a fee or a certificate to support .mdz. You check your app against the public conformance guide yourself, and getting listed on Works With is a public issue anyone can open. And these are MDZip's choices, not rules for you. MDZip's own apps are there to test, prove and promote the spec, not to be the only way to use it, so if you'd like to sell your app or publish it in an app store, go ahead. The libraries are free for that too.

Your files outlive us

An .mdz is a standard ZIP file with Markdown inside. If MDZip disappeared tomorrow, you could rename any .mdz to .zip, open it with the tools your computer already has, and read every word in a text editor.

Small and stable

The spec adds only what a document needs: where to start reading, a little optional information about it, and rules that keep files safe to open. Every file records the spec version it was written for, so tools can tell old files from new ones.

Built in the open, with AI

Most of the code is written by AI agents, and a person reviews every change before it ships. Correctness doesn't rest on trusting the AI: the shared fixtures, each repository's checks and this site's build catch mistakes. More on how MDZip is built.

Who's behind it

Kyle White

I'm Kyle White, a software architect in Sacramento, California. I started MDZip and I maintain it: I design how the pieces fit together, decide what goes in and review every change. AI agents do most of the typing.

I began my career as an electronics engineer, helped build the show control system for Mickey's Toontown at Disneyland, and co-founded a company that tracked stolen vehicles before moving fully into software.

Most of my career since has gone into getting systems to talk to each other, often for California state agencies. I architected the File Interface Staging Engine, which kept departments' older systems in step with FI$Cal, the state's financial system, and I've written my share of specs, proposals and user manuals along the way. If engineering has taught me one thing, it's that communication is the most important part of it. MDZip comes from the same place: a file format, like an interface between systems, only works if everyone on both sides agrees on it, and only lasts if it's written down clearly.

I started MDZip because of an everyday annoyance. When I wanted a note with a few pictures in it, I had three choices, and none of them was good. I could open Word, or something like it, which was slow, buggy and far more than a note needed. I could use a note app like OneNote or Notion, where the note only really lived inside that app. Or I could write in Markdown and put up with image files that never quite stayed with the text. I wanted one answer that every app could share.

There's more from me at Kyle's Technobabble, on LinkedIn and on GitHub.

Get in touch

This page renders from about.mdz (MDZip, ~71 KB, updated 2026-11-09) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.