Add MDZip to Your App
This page is for developers of Markdown editors, note apps and converters who want their app to open or save .mdz files. Support comes in steps, and each one is useful on its own. MDZip's libraries handle the format itself (finding the main document, matching paths, reading and writing the manifest, rejecting unsafe archives), so most of the work is connecting them to your app.
If you use an AI coding assistant, skip to prompts for your AI assistant.
Choose how far to go
| Step | What your users get | Work |
|---|---|---|
| 1. Open | Read an .mdz someone sent them, pictures included |
Small |
| 2. Export | Share a note and its images as one file | Small |
| 3. Drop-in viewer | A full preview with navigation and multi-document archives (browser and webview apps) | Moderate |
| 4. Edit in place | Open an .mdz, change it and save it back |
Larger: your app decides how saving works |
Steps 1 and 2 together cover sharing. Step 4 is what lets people keep their documents as .mdz in your app.
Choose a library
| Platform | Library | Install |
|---|---|---|
| JavaScript and TypeScript: browser, Electron, Tauri, Node.js | @mdzip/core-js |
npm install @mdzip/core-js |
| Browser and webview UI | @mdzip/editor, a ready-made viewer and editor (with React, Vue and Angular wrappers) |
npm install @mdzip/editor |
| .NET 8 and later | MDZip.Core |
dotnet add package MDZip.Core |
| Rust 1.85 and later | mdzip-core (API docs) |
cargo add mdzip-core |
| Python 3.10 and later | mdzip-core, standard library only |
pip install mdzip-core |
| Lua 5.3 and 5.4: Pandoc filters, scripts | mdzip-core-lua, pure Lua with no dependencies |
luarocks install mdzip-core-lua |
| iOS 15 and later, macOS 12 and later, Linux: Swift | mdzip-core-swift |
Swift Package Manager: https://github.com/mdzip-project/mdzip-core-swift |
| Android 5.0 and later, Java 8 and later: Kotlin or Java | org.mdzip:mdzip-core, no dependencies beyond the Kotlin standard library |
Gradle: implementation("org.mdzip:mdzip-core:0.1.0") |
| Scripts and anything else | The mdz CLI |
winget install MDZip.Cli, or see Install |
All of them are open source under the Apache 2.0 license, and the core libraries run the specification's shared test files. The examples below use JavaScript and .NET; the Rust, Python, Lua, Swift and Kotlin libraries have the same operations, shown in their READMEs.
No core library for your language? You can build one with an AI assistant.
Step 1: Open and show
Open the archive, find its main document and render it with the Markdown renderer your app already uses. Then point each image at its copy inside the archive:
import { MdzArchiveCore } from '@mdzip/core-js';
const archive = await MdzArchiveCore.open(bytes); // Uint8Array, ArrayBuffer or Blob
const entry = await archive.resolveEntryPoint(); // the main document, e.g. "index.md"
const markdown = await archive.readText(entry);
// Render with your own Markdown renderer and sanitizer, into a <template>
// so the browser doesn't try to fetch the images from your own server.
const template = document.createElement('template');
template.innerHTML = sanitize(renderMarkdown(markdown));
// Point each image at its copy inside the archive, then show the result.
for (const img of template.content.querySelectorAll('img')) {
const target = archive.resolveLink(entry, img.getAttribute('src') ?? '', undefined, { use: 'embed' });
if (target.kind === 'internal') img.src = await archive.readDataUri(target.entry);
else if (target.kind !== 'url') img.removeAttribute('src'); // missing: don't look elsewhere
}
preview.replaceChildren(template.content);
Image paths are relative to the document that uses them, so resolveLink takes the document's path too. It also turns away paths that would leave the archive. Images from the web (https:) are left as they are.
In .NET:
using MDZip.Core;
var entry = MdzArchive.ResolveEntryPointStrict("notes.mdz"); // the main document
var markdown = MdzArchive.ReadText("notes.mdz", entry);
// For each image in the rendered document:
var target = MdzArchive.ResolveLink("notes.mdz", entry, src, use: "embed");
if (target.Kind == "internal")
src = MdzArchive.ReadDataUri("notes.mdz", target.Entry!);
Errors such as an archive with no main document come back with a code at the start of the message (ERR_ENTRYPOINT_MISSING, for example), so show the message to the user.
Step 2: Export
Pack the document and the images it uses into a new archive. Rewrite the image references in the Markdown so they point at the paths inside the archive:
import { MdzPackagerCore } from '@mdzip/core-js';
const files = [
{ path: 'index.md', text: noteMarkdown }, // image links point at images/...
{ path: 'images/beach.png', data: imageBytes }, // every image the note uses
];
const { blob } = await MdzPackagerCore.buildArchive(files, 'Trip notes', {
title: 'Trip notes',
entryPoint: 'index.md',
createIndex: false,
mapFiles: false,
filters: ['**/*'],
});
const bytes = new Uint8Array(await blob.arrayBuffer()); // write these bytes to disk
filters decides which files go in, so it must be ['**/*']: an empty list leaves every file out. The library writes the manifest.json for you.
In .NET:
MdzArchive.CreateFromFiles("trip.mdz",
new[] { ("index.md", "note/index.md"), ("images/beach.png", "note/images/beach.png") },
new Manifest { Title = "Trip notes", EntryPoint = "index.md" }); // using MDZip.Core.Models
Step 3: Use the drop-in viewer
For an app built on web technology, @mdzip/editor gives you the same viewer and editor as MDZip Studio and the VS Code extension: rendering, images, navigation between documents, and Mermaid diagrams.
import { MdzipWorkspaceView } from '@mdzip/editor';
const view = new MdzipWorkspaceView(container, {
controls: 'viewer', // or 'hosted-editor' to edit
onFailed: (error) => console.error(error),
});
await view.open(bytes, { mode: 'read-only', fileName: 'notes.mdz' });
The Editor Developer Guide covers editing, saving, theming and the framework wrappers.
Step 4: Save changes back
Write only what changed. The library keeps everything else in the archive as it was, including images, files your app doesn't know about and manifest fields written by other apps:
const { blob } = await MdzArchiveCore.updateFiles(original, [
{ path: entry, content: editedMarkdown },
]);
In .NET, MdzArchive.UpdateFiles("notes.mdz", new[] { new ArchiveWriteSpec(entry, "edited.md") }) does the same from a local file.
Don't extract the archive to a folder and zip it up again with a general ZIP tool. That loses anything your app didn't understand, and the result may not be a valid .mdz.
Rules your app is responsible for
The libraries handle most of the specification. These parts are up to your app:
- Never run anything from an archive. Sanitize the rendered HTML, as you would for any Markdown from someone else: no scripts, no event handlers, no
javascript:links (§13.2). - Load images from inside the archive only. Don't fetch an archive's images from the web or from files next to it unless the user turns that on (§9.6). Resolve them before the HTML reaches the page, as in step 1.
- Treat paths as case-sensitive.
Images/Logo.pngandimages/logo.pngare different files. The libraries match paths this way; keep your own lookups the same. - Open
.mdzfiles by extension, and use the media typeapplication/vnd.mdzipwhere your platform needs one (§10).
Test your support
- Conformance Guide: what the specification requires of an app that opens, creates or saves
.mdzfiles, as checklists, with sample files for each behavior and a prompt for having an AI assistant write tests from the conformance tests. - Example archives: a minimal file, one with images and a multi-document project.
- Conformance tests: the specification's test cases and fixture archives, including tricky entry points, unusual paths and a hostile-content archive that checks your preview runs no scripts.
mdz validate: check the files your app writes. Aim for no warnings as well as no errors.
Prompts for your AI assistant
Paste one of these into your AI coding assistant, in your app's project. Each one names the library calls to use and the mistakes to avoid. We tested them on 2026-10-21 with two small sample apps that had never seen MDZip, a browser Markdown editor and a .NET converter. Each one worked on the first try, and we checked the results with mdz validate and a browser.
Open .mdz files (JavaScript or TypeScript)
Add read-only support for opening MDZip (.mdz) files to this app.
An .mdz is a ZIP archive holding one or more Markdown documents, the images they use and a manifest.json. Spec: https://mdzip.org/spec.html. Developer guide: https://mdzip.org/docs/integrate.html
Use the npm package @mdzip/core-js (install that exact name; some older docs say "mdzip-core-js", which is wrong). Read node_modules/@mdzip/core-js/README.md and AGENTS.md, and the type definitions in its dist/ folder, before writing code.
- Accept .mdz wherever the app accepts .md files today.
- Open it with MdzArchiveCore.open(bytes) and find the main document with archive.resolveEntryPoint(). Don't guess it from file names.
- Render the main document with the app's existing Markdown renderer and sanitizer.
- Show its images from inside the archive. Do this before the HTML is added to the page (for example, in a <template>), so the browser never requests them from anywhere else. For each <img> (Markdown and raw HTML images alike), pass its src attribute as rendered to archive.resolveLink(entry, src, undefined, { use: 'embed' }):
- kind 'internal': set src to await archive.readDataUri(result.entry);
- kind 'url' (https: and data: images): leave it as it is;
- anything else: the image isn't in the archive, so remove the src.
- If the preview re-renders while the user types, cache the data URLs instead of reading the archive again each time.
- Don't extract the archive to disk or a temp folder.
- Keep it read-only for now: don't write changes back into the .mdz. Tell me how saving behaves after opening one.
- If the file isn't a valid .mdz, show the error message (it starts with an ERR_ code) instead of failing silently.
When you're done, build the project and test it with https://mdzip.org/examples/with-images.mdz and with a sample .mdz whose main document is in a subfolder and uses an image in another folder. List the files you changed.
Export as .mdz (JavaScript or TypeScript)
Add "Export as .mdz" to this app, next to its other export options.
An .mdz (MDZip) is a ZIP archive holding a Markdown document, the images it uses and a manifest.json. Spec: https://mdzip.org/spec.html. Developer guide: https://mdzip.org/docs/integrate.html
Use the npm package @mdzip/core-js (install that exact name; some older docs say "mdzip-core-js", which is wrong). Read node_modules/@mdzip/core-js/README.md and AGENTS.md, and the type definitions in its dist/ folder, before writing code.
- Package the current document as index.md with MdzPackagerCore.buildArchive(files, title, { title, entryPoint: 'index.md', createIndex: false, mapFiles: false, filters: ['**/*'] }). Files are { path, text } for the Markdown and { path, data } (a Uint8Array) for images. filters must be ['**/*']: an empty list leaves every file out.
- Include every image the document uses that the app can read: images embedded as data: URLs, and local files if the app has access to them. Put them under images/ and rewrite the document's image references, Markdown and HTML <img> alike, to those relative paths, percent-encoding spaces, #, ? and %. Leave http: and https: images as they are.
- Give each image its own path, even when two have the same name. Use the same path when the same image is used twice.
- If an image can't be read, still export, and tell the user which images were left out.
- Use the document's first heading as the title, or else its file name.
- Don't change how the app saves .md files.
When you're done, build the project, export a document with at least two images, check the result with MdzArchiveCore.validate() (no errors or warnings), check that every rewritten image path is in the archive, and list the files you changed.
Open .mdz files (.NET)
Add support for MDZip (.mdz) files as input to this app.
An .mdz is a ZIP archive holding one or more Markdown documents, the images they use and a manifest.json. Spec: https://mdzip.org/spec.html. Developer guide: https://mdzip.org/docs/integrate.html
Use the NuGet package MDZip.Core (namespace MDZip.Core). Its README doesn't list every method; the ones below exist.
- Find the main document with MdzArchive.ResolveEntryPointStrict(path) and read it with MdzArchive.ReadText(path, entry). Don't guess it from file names.
- For each image the document uses, Markdown and raw HTML <img> alike, call MdzArchive.ResolveLink(path, entry, src, use: "embed") with the URL as the Markdown parser gives it:
- Kind "internal": use MdzArchive.ReadDataUri(path, target.Entry) as the image source;
- Kind "url" (https: and data: images): leave it as it is;
- anything else: the image isn't in the archive; leave it, and warn the user.
- Don't extract the archive to disk or a temp folder.
- Errors are InvalidOperationExceptions whose message starts with an ERR_ code (MdzSpec.ErrorCode(ex) reads it). Report them as one line, not a stack trace.
When you're done, build the project and test it with https://mdzip.org/examples/with-images.mdz and with a sample .mdz whose main document is in a subfolder and uses an image in another folder (set entryPoint in its manifest.json). List the files you changed.
Build a core library for another language
For a language that doesn't have an MDZip library yet. Replace <language> in the first line with yours.
Build an MDZip core library for <language>: a library that other apps use to read, write and validate MDZip (.mdz) files.
An .mdz is a ZIP archive holding one or more Markdown documents, the files they use and a manifest.json. Read these before writing code:
- Specification: https://github.com/mdzip-project/mdzip-spec/blob/main/SPEC.md (sections 4-6, 9, 13 and 14 matter most). Where anything below disagrees with it, the specification wins.
- Core library contract, the operations every MDZip core provides (R1-R7): https://github.com/mdzip-project/.github/blob/main/docs/core-contract.md
- Shared test fixtures, with each test and its expected result: https://github.com/mdzip-project/mdzip-spec/tree/main/fixtures
What to build:
- The contract's required operations R1-R7: open an archive; list entries and read their bytes and UTF-8 text; read the manifest, entry point and mode; resolve links; validate; create an archive; modify one (add, replace and remove entries, update metadata); enforce the safety rules. Name the API the way developers in that language expect. Leave out the optional extensions.
- Report errors with the spec's codes (ERR_ENTRYPOINT_MISSING and the others in Section 16) in a form callers can check without parsing the message.
- Find the entry point with the spec's algorithm (Section 5.5). An entryPoint that is invalid or names a missing file is an error, never a silent fallback to index.md or README.md.
- Match paths case-sensitively after NFC normalization, and never substitute a file with different case. Compare support file names (README, AGENTS, LICENSE and so on) ASCII case-insensitively, not with locale rules.
- When modifying an archive, keep every other entry's path and bytes unchanged and keep unknown manifest fields. If a write fails, leave the original file as it was.
- Write only compression methods 0 (stored) and 8 (deflate), set the UTF-8 flag on non-ASCII names, and write no ZIP64 records unless a value doesn't fit without them. Some ZIP libraries always write ZIP64; check yours. When reading, reject other methods with ERR_ZIP_INVALID.
- While reading, limit entry count, total uncompressed size and compression ratio, checking the bytes actually decompressed and not only the sizes the archive declares (ERR_LIMIT_EXCEEDED). Never follow symbolic links.
- Don't render Markdown; the apps using the library do that.
- Use a well-maintained ZIP library, and avoid other dependencies unless you need them. If no ZIP library can follow these rules (some can't stop decompressing at the declared size, or always write ZIP64), tell me why, and write only the parts that are missing.
How to test it:
- Copy the fixtures from the latest released spec tag, as the fixtures README describes, and run every consumer test (T-001 onward; T-016 is only for apps that render) and producer check (P-001 onward) through the library's public API.
- Report each test as passed, failed or not applicable, with the reason for any that don't pass. Don't change a fixture or its expected result to make a test pass; if you think one is wrong, tell me.
- If the mdz CLI is installed (https://mdzip.org/docs/cli.html), run mdz validate on archives the library writes. Aim for no errors and no warnings.
The existing cores (JavaScript, .NET, Rust, Python, Lua, Swift and Kotlin, listed at https://mdzip.org/docs/integrate.html#choose-a-library) show how others handled a rule, but follow the specification and the fixtures, not another core's details. Finish with a README that maps R1-R7 to the public API, and list what's left to do.
We used this prompt on 2026-10-28 to build the Lua core library. It took Claude Opus 5.5 in Claude Code about 25 minutes, and the result passes every conformance test that applies to a library.
Tell us about it
When your app supports .mdz, or you've built a library, open an issue so we can list it on Works With. The Conformance Guide says what a listing needs. Questions about the format or the libraries are welcome there too.
This page renders from integrate.mdz (MDZip, ~10 KB, updated 2026-11-10) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.