A review of the spec

[lvarvel]

I like the limitations on pathing, nicely thought through. Personal taste, I would mandate a more strict format with there always being a manifest.json with an entryPoint defined. The flexible entry points seem potentially messy on the consumer side.

Other than that, seems pretty good. You inherit the problems of zip, but also inherit all the work done on mitigating those problems.

Overall, the spec seems quite clear.  It would be helpful to get a few examples of use cases, for inspiration. TBH it's not exactly clear where I would use .mdz in a project right now.

[kylemwhite]

Thanks — that’s helpful feedback.

The optional manifest.json is an intentional design choice (I went back and forth on that one). Requiring a manifest and explicit entryPoint would simplify things for consumers, but the goal of MDZ is to keep the minimum valid package very lightweight: essentially a ZIP with Markdown content and a simple, deterministic fallback discovery rule (it’s intentionally minimal).

In practice, I think this is mostly an edge case. Most producers will include a manifest anyway. The main reason for allowing it to be optional is to keep the format easy to experiment with — e.g. a dev zips up a single .md file, renames it to .mdz, and tries it. If that fails just because a manifest is missing, the natural reaction is “there’s only one file in there, why can’t you just use that?”, which is a reasonable reaction.

I’ll likely add stronger guidance recommending that producers include manifest.json with an explicit entryPoint for better interoperability.

I also agree on the need for clearer use cases. The spec may be understandable, but the “when would I use this?” part isn’t obvious yet. I’ll add some concrete examples like portable documentation bundles, offline review packages, wiki/project exports, and book/article bundles.