Download this page as .mdz

Core libraries

Add MDZip (.mdz) support to an app or a script with a core library in your language. The libraries read, create, update and validate archives; your app supplies the Markdown renderer and user interface.

Use a core or write your own?

An .mdz file is a ZIP archive, so reading one with your language's ZIP library looks like an afternoon's work. Most of the effort is in the rules on top of the ZIP: which file to open first, which entry names are unsafe, how links resolve, and what to keep when saving. A core already follows all of them.

Use a core Write your own
Conformance Passes the specification's shared conformance tests as soon as you install it, including ZIP bombs, symbolic links and Unicode file names. You work through the conformance checklist and run the same tests yourself.
Spec updates Update the package. The cores are kept in step with the specification and re-tested against each release. You follow the specification's changelog and update your code and tests.
Safety Unsafe paths and symbolic links are refused, and oversized or hostile archives are rejected before their data is decompressed. Many ZIP libraries trust an entry's declared size or follow symbolic links; you add those checks.
Errors Stable error codes, the same in every language, so you can tell users exactly what's wrong with a file. You design your own, or copy the specification's.
Compatibility Files open and save the same way as in other MDZip apps, and files and manifest fields your app doesn't use are kept. Small differences show up as files that open differently elsewhere, or lose data when saved.
Cost One Apache 2.0 dependency. The .NET, Python, Lua and Kotlin cores need nothing else. No dependency, but more code to own.
Control Most cores hold the whole archive in memory, and some have fixed resource limits. You decide how archives are read, streamed and limited.

Write your own when your language has no core yet, or when you need something a core doesn't offer, such as streaming very large archives. Add MDZip to your app has a prompt for having an AI assistant build one against the same tests.

Choose a library

Language Runtime Availability Get started
.NET .NET 8 or .NET 10 Available MDZip.Core
JavaScript/TypeScript Node.js or a modern browser Available @mdzip/core-js
Python Python 3.10+ Available mdzip-core
Rust Rust 1.85+ Available mdzip-core
Lua Lua 5.3 or 5.4 Available mdzip-core-lua
Swift Swift 5.9+ on macOS, iOS or Linux Available mdzip-core-swift
Kotlin and Java Android 5.0+ or Java 8+ Available org.mdzip:mdzip-core

Each core handles archive entries and metadata, entry-point discovery, relative links, validation, creation, modification and built-in resource limits. Optional features differ: .NET and JavaScript include workspace models and unused-image analysis; Python, Rust and Swift focus on archive operations and offer configurable resource limits; Lua and Kotlin focus on archive operations with fixed limits. See each library's documentation for the exact API and limits.

Common operations

Every core provides the same basic operations: open an archive, list and read its files, find the main document, read the manifest, resolve links, validate, create a new archive, and add, replace or remove files. Each library's section below has an example and a table of its method names. Failures carry a stable error code in every core.

Some cores add optional extras on top of these:

Extra Where
Pack a folder into an archive .NET Create, JavaScript packDirectory (Node.js), Python mdzip_core.create_from_directory, Rust mdzip_core::create_from_directory
Extract an archive to a folder .NET Extract, JavaScript extractArchive (Node.js)
Workspace model for editors .NET OpenWorkspace, JavaScript openWorkspace
Find unused images .NET FindOrphanedAssets, JavaScript findOrphanedAssets
Set your own resource limits Python limits= on open, Rust open_with_limits, Swift limits: on MDZipArchive

Cores without an extract function can still read every file, so an app can write them out itself.

Each example below opens an existing guide.mdz, prints its main document and file list, reports any validation errors, and saves a copy with a notes.md added. You can make one with the packager, MDZip Studio, or the mdz CLI.

.NET

Use MDZip.Core in a .NET 8 or .NET 10 application. It provides archive operations, directory packaging and extraction, link resolution, a workspace model and unused-image analysis.

Install from NuGet:

dotnet add package MDZip.Core
using MDZip.Core;

var entry = MdzArchive.ResolveEntryPointStrict("guide.mdz");
Console.WriteLine(MdzArchive.ReadText("guide.mdz", entry));

foreach (var path in MdzArchive.List("guide.mdz"))
    Console.WriteLine(path);

foreach (var error in MdzArchive.Validate("guide.mdz").Errors)
    Console.WriteLine(error);

// Copy the archive, then add notes.md from disk to the copy.
File.Copy("guide.mdz", "guide-notes.mdz", overwrite: true);
MdzArchive.UpdateFiles("guide-notes.mdz", [new ArchiveWriteSpec("notes.md", "notes.md")]);

Resource limits are built in and fixed. Resolve links through the core before loading an archive's images or other resources; an app displaying the document is responsible for sanitizing rendered HTML.

Common operations

Task Method
Open an archive None: pass the path to each call
List files List
Find the main document ResolveEntryPointStrict
Read a file as text ReadText
Read a file as bytes ReadBytes
Read the manifest ReadManifest
Resolve a link ResolveLink
Validate Validate
Create an archive CreateFromFiles
Add, replace or remove files UpdateFiles

All of these are static methods on MdzArchive.

NuGet package · Repository and API reference · Share this section

JavaScript/TypeScript

Use @mdzip/core-js in Node.js or a modern browser. The package includes TypeScript declarations, archive operations, a workspace model and unused-image analysis. Its Node.js entry point adds directory packaging and extraction.

Install from npm:

npm install @mdzip/core-js

This example runs in Node.js as an ES module (.mjs):

import { readFile, writeFile } from 'node:fs/promises';
import { MdzArchiveCore } from '@mdzip/core-js';

const bytes = await readFile('guide.mdz');
const archive = await MdzArchiveCore.open(bytes);
console.log(await archive.readText(await archive.resolveEntryPoint()));
console.log(archive.listPaths());

const { errors } = await archive.validate();
errors.forEach(error => console.log(error));

// Add notes.md and save the result as a new archive.
const updated = await MdzArchiveCore.updateFiles(bytes, [{ path: 'notes.md', content: '# Notes\n' }]);
await writeFile('guide-notes.mdz', new Uint8Array(await updated.blob.arrayBuffer()));

In a browser, pass the selected File or an ArrayBuffer to MdzArchiveCore.open() instead. Use @mdzip/core-js/node only in Node.js. The default ZIP implementation enforces built-in resource limits; a custom ZIP implementation has different responsibilities, described in the README.

Common operations

Task Method
Open an archive MdzArchiveCore.open
List files listPaths
Find the main document resolveEntryPoint
Read a file as text readText
Read a file as bytes readBytes
Read the manifest readManifest
Resolve a link resolveLink
Validate validate
Create an archive MdzPackagerCore.buildArchive
Add, replace or remove files MdzArchiveCore.updateFiles

Names without a prefix are methods on the opened archive.

npm package · Repository and API examples · Share this section

Python

Use mdzip-core with Python 3.10 or newer. It uses only the standard library, with no additional dependencies, and includes configurable resource limits and filesystem link resolution.

Install from PyPI:

python -m pip install mdzip-core
import mdzip_core

with mdzip_core.open("guide.mdz") as archive:
    print(archive.read_text(archive.entry_point))
    print(archive.files)
    for finding in archive.validate():
        if finding.level == "error":
            print(finding.code, finding.message)

# Add notes.md and save the result as a new archive.
data = mdzip_core.update("guide.mdz", write={"notes.md": "# Notes\n"})
with open("guide-notes.mdz", "wb") as file:
    file.write(data)

Install mdzip-core and import mdzip_core. The unrelated package named mdzip is a different project. Archives are held in memory; opening one does not extract it to disk. This core does not include an editor workspace model or unused-image analysis.

Common operations

Task Method
Open an archive mdzip_core.open
List files files
Find the main document entry_point
Read a file as text read_text
Read a file as bytes read_bytes
Read the manifest manifest
Resolve a link resolve_link
Validate validate
Create an archive mdzip_core.create
Add, replace or remove files mdzip_core.update

Names without a prefix are methods or properties of the opened archive.

PyPI package · Repository and API reference · Share this section

Rust

Use the mdzip-core crate with Rust 1.85 or newer. It has pure Rust dependencies, needs no async runtime, and includes configurable resource limits and filesystem link resolution.

Add the crate:

cargo add mdzip-core
use mdzip_core::{Level, MdzArchive, Update};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let archive = MdzArchive::open_path("guide.mdz")?;
    let entry = archive.entry_point()?;
    println!("{}", archive.read_text(&entry)?);
    for path in archive.files() {
        println!("{path}");
    }

    for finding in archive.validate() {
        if finding.level == Level::Error {
            println!("{} {}", finding.code, finding.message);
        }
    }

    // Add notes.md and save the result as a new archive.
    let bytes = archive.update(&Update::new().write("notes.md", "# Notes\n"))?;
    std::fs::write("guide-notes.mdz", bytes)?;
    Ok(())
}

Archives are held in memory. The crate handles archive operations and does not include an editor workspace model or unused-image analysis.

Common operations

Task Method
Open an archive MdzArchive::open_path
List files files
Find the main document entry_point
Read a file as text read_text
Read a file as bytes read_bytes
Read the manifest manifest
Resolve a link resolve_link
Validate validate
Create an archive mdzip_core::create
Add, replace or remove files update

Names without a prefix are methods on the opened archive.

Crate on crates.io · API documentation · Repository · Share this section

Lua

Use mdzip-core-lua with Lua 5.3 or 5.4. It is pure Lua, with no C modules and no dependencies: ZIP, DEFLATE, CRC-32, JSON and Unicode normalization are built in, so it also runs in hosts that can't load C modules, such as Pandoc.

Install from LuaRocks:

luarocks install mdzip-core-lua

Install mdzip-core-lua and require mdzip. Functions that can fail return nil, err, the usual Lua convention:

local mdzip = require("mdzip")

local archive = assert(mdzip.open_file("guide.mdz"))
print(assert(archive:read_text(assert(archive:entry_point()))))
for _, path in ipairs(archive:files()) do print(path) end

for _, err in ipairs(archive:validate().errors) do
  print(err.code, err.message)
end

-- Add notes.md and save the result as a new archive.
local bytes = assert(archive:update({ put = { { path = "notes.md", text = "# Notes\n" } } }))
local file = assert(io.open("guide-notes.mdz", "wb"))
file:write(bytes)
file:close()

Archives are held in memory, and resource limits are built in and fixed. LuaJIT, and so Neovim, isn't supported yet. This core does not include an editor workspace model or unused-image analysis.

Common operations

Task Method
Open an archive mdzip.open_file
List files files
Find the main document entry_point
Read a file as text read_text
Read a file as bytes read
Read the manifest manifest
Resolve a link resolve_link
Validate validate
Create an archive mdzip.create
Add, replace or remove files update

Names without a prefix are methods on the opened archive, called with :.

Rock on LuaRocks · Repository and API reference · Share this section

Swift

Use mdzip-core-swift in iPhone and iPad apps (iOS 15 and later), Mac apps (macOS 12 and later) and on Linux, with Swift 5.9 or later. Its one dependency, ZIPFoundation, is used only to write archives.

Add it in Xcode under File → Add Package Dependencies… with https://github.com/mdzip-project/mdzip-core-swift, or in Package.swift:

.package(url: "https://github.com/mdzip-project/mdzip-core-swift.git", from: "0.1.0")
import Foundation
import MDZip

let archive = try MDZipArchive(contentsOf: URL(fileURLWithPath: "guide.mdz"))
print(try archive.text(at: try archive.entryPoint()))
print(archive.files.map(\.path))

for finding in archive.validate().errors {
    print(finding.code, finding.message)
}

// Add notes.md and save the result as a new archive.
let data = try archive.updated { try $0.setFile("notes.md", text: "# Notes\n") }
try data.write(to: URL(fileURLWithPath: "guide-notes.mdz"))

Failures are MDZipError values with a stable code. Archives are held in memory; resource limits are built in, and you can pass your own. This core does not include an editor workspace model or unused-image analysis.

Common operations

Task Method
Open an archive MDZipArchive(contentsOf:)
List files files
Find the main document entryPoint
Read a file as text text(at:)
Read a file as bytes data(at:)
Read the manifest manifest
Resolve a link resolveLink(_:from:)
Validate validate
Create an archive MDZipBuilder
Add, replace or remove files updated or editor

Names without a prefix are methods or properties of the opened archive.

Repository and API reference · Release notes · Share this section

Kotlin and Java

Use org.mdzip:mdzip-core in Android apps (Android 5.0 and later) and on the JVM (Java 8 and later), from Kotlin or Java. It has no dependencies beyond the Kotlin standard library, and it opens archives from a byte array or a stream, such as one from Android's ContentResolver.

Add it with Gradle:

dependencies {
    implementation("org.mdzip:mdzip-core:0.1.0")
}
import org.mdzip.core.MdzArchive
import java.io.File

fun main() {
    val archive = MdzArchive.open(File("guide.mdz"))
    println(archive.readText(archive.entryPoint()))
    println(archive.files)

    for (error in archive.validate().errors) {
        println("${error.code} ${error.message}")
    }

    // Add notes.md and save the result as a new archive.
    archive.edit().setText("notes.md", "# Notes\n").writeTo(File("guide-notes.mdz"))
}

Failures are MdzException values with a stable code, such as ERR_ENTRYPOINT_MISSING. Archives are held in memory, and resource limits are built in and fixed. This core does not include an editor workspace model or unused-image analysis.

Common operations

Task Method
Open an archive MdzArchive.open
List files files
Find the main document entryPoint
Read a file as text readText
Read a file as bytes readBytes
Read the manifest manifest
Resolve a link resolveLink
Validate validate
Create an archive MdzBuilder
Add, replace or remove files edit

Names without a prefix are methods or properties of the opened archive.

Package on Maven Central · Repository and API reference · Share this section

Put a core to work

Read Add MDZip to your app for integration guidance, or the specification for the format rules. Core libraries provide archive data; an app that displays that data must also handle rendering, sanitization and resource loading.

Need a ready-made editing interface? See the web editor and the editor integration docs.

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