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.

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.

The examples below read an existing guide.mdz and print its main Markdown document. 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");
var markdown = MdzArchive.ReadText("guide.mdz", entry);
Console.WriteLine(markdown);

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.

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 } from 'node:fs/promises';
import { MdzArchiveCore } from '@mdzip/core-js';

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

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.

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))

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.

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::MdzArchive;

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)?);
    Ok(())
}

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

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"))
local entry = assert(archive:entry_point())
print(assert(archive:read_text(entry)))

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.

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 MDZip

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

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.

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()))
}

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.

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, ~4 KB, updated 2026-11-06) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.