Crate mdzip_core 

Read and write MDZip (.mdz) archives: one or more Markdown documents and their images and other assets, in a single ZIP file.

This crate implements the MDZip specification 1.2.0 and is tested against the specification’s shared conformance fixtures, the same ones the JavaScript, .NET and Python cores run, so an archive written here opens the same way in every MDZip tool.

Reading

use mdzip_core::MdzArchive;

let archive = MdzArchive::open(data)?;          // or MdzArchive::open_path("guide.mdz")
let entry = archive.entry_point()?;             // "index.md" (Section 5.5)
let text = archive.read_text(&entry)?;
assert_eq!(archive.title(), Some("My guide"));
for finding in archive.validate() {             // conformance notes; never fails
    println!("{} {} {}", finding.level, finding.code, finding.message);
}

Opening is safe for untrusted input: invalid or encrypted ZIPs, unsafe or duplicate entry names, ZIP bombs and newer major spec versions are rejected with a stable ErrorCode, and symbolic links are never followed. See MdzArchive::open.

Writing

use mdzip_core::{create, Application, CreateOptions};

let data = create(
    [
        ("index.md", "# My guide\n\n![logo](images/logo.png)\n".as_bytes()),
        ("images/logo.png", b"\x89PNG..."),
    ],
    &CreateOptions::new().application(Application::new("my-editor", "1.0")),
)?;

Every archive gets the manifest.json the spec requires of producers. To change an existing archive, use MdzArchive::update: untouched entries and unknown manifest fields are kept exactly.

Links

MdzArchive::resolve_link resolves a link written in a document, per Sections 9.3–9.6. For links out of the archive to files beside it, or into other archives, supply a LinkHost such as FilesystemHost to resolve_link.

Structs

Application

The application writing the archive, recorded in producer.application.

CreateOptions

Options for create.

Diagnostic

A finding from opening or validating an archive.

EntryInfo

ZIP metadata of one entry.

FilesystemHost

A LinkHost backed by a directory on disk.

HostOptions

Options for FilesystemHost.

Limits

Resource limits applied when opening and reading archives (Section 13.1).

MdzArchive

An opened, read-only .mdz archive.

MdzError

An MDZip error: a stable ErrorCode and a human-readable message.

ParsedManifest

A parsed manifest and the names of members it repeats (Section 6.4).

Update

Changes for MdzArchive::update. Build one with the methods below.

Enums

ErrorCode

A stable, machine-readable error code, such as ERR_ENTRYPOINT_MISSING.

HostKind

What exists at a host path.

Level

How serious a Diagnostic is.

LinkSource

Where a link was written.

LinkTarget

Where a link points. Fragments (#section) are kept, without the #.

LinkUse

Whether a link is followed by the user or loaded automatically.

Mode

How an archive is interpreted (Section 5.7).

UnresolvedReason

Why a link didn’t resolve.

Constants

DEFAULT_FILTERS

Markdown and common image types: the default for create_from_directory.

MANIFEST_NAME

The manifest’s entry name (Section 6).

PRODUCER_CORE_NAME

This library, as written in producer.core (Section 6.1).

SPEC_NAME

The spec name written in spec.name.

SPEC_VERSION

The MDZip specification version this library implements and writes.

SUPPORTED_MAJOR

The newest spec major version this library reads (Section 11.2).

SUPPORT_FILE_NAMES

Support file names (Section 5.5), compared ASCII case-insensitively, with a .md or .markdown extension.

Traits

LinkHost

What link resolution needs to know about the files around an archive.

Functions

check_spec_version

Reject a spec or spec.version with the wrong type, a version that isn’t semantic versioning, or a newer major version than this library supports (Section 11.2). A missing version is read as 1.x (Section 11.3).

create

Build a new .mdz archive and return its bytes.

create_from_directory

Pack a folder into an .mdz, with paths relative to directory.

is_markdown

True for .md and .markdown files, extension compared ASCII case-insensitively (Section 7.3).

is_mdz_name

True for a name with an .mdz extension, compared ASCII case-insensitively.

is_support_file

True for a root-level support file (Section 5.5): README, AGENTS, LICENSE, CHANGELOG or CONTRIBUTING, with .md or .markdown.

manifest_mode

The archive’s mode (Section 5.7): document when mode is absent.

matches_filters

True if path (/-separated, relative) matches any of the glob filters.

nfc

The path in Unicode Normalization Form C.

parse_manifest

Parse manifest.json bytes (UTF-8 JSON, optional BOM).

resolve_entry_point

The archive’s primary Markdown file, by the ordered algorithm in Section 5.5.

resolve_link

Resolve link written in source (Sections 9.3–9.6).

same_path

Path equality per Section 5.4.1: case-sensitive, after NFC normalization.

serialize_manifest

Serialize a manifest as UTF-8 JSON with LF line endings, keeping field order.

spec_version

The manifest’s spec.version, if it has one.

update

Open data, apply changes and return the new bytes. See MdzArchive::update.

validate_entry_set

Check that a set of entry names can form one archive (Section 5.4).

validate_manifest

Validate a parsed manifest (Section 6.4) and return the descriptive fields to ignore because they have the wrong type or an invalid value.

validate_path

Check that path is a valid archive entry name (Section 5.4).

Type Aliases

Manifest

A parsed manifest.json: the top-level JSON object, with field order kept.

Result

Result with MdzError.