MDZip.Core 2.0.1

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package MDZip.Core --version 2.0.1
                    
NuGet\Install-Package MDZip.Core -Version 2.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MDZip.Core" Version="2.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MDZip.Core" Version="2.0.1" />
                    
Directory.Packages.props
<PackageReference Include="MDZip.Core" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MDZip.Core --version 2.0.1
                    
#r "nuget: MDZip.Core, 2.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MDZip.Core@2.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MDZip.Core&version=2.0.1
                    
Install as a Cake Addin
#tool nuget:?package=MDZip.Core&version=2.0.1
                    
Install as a Cake Tool

MDZip.Core

Core .NET library for working with .mdz archives.

Formerly published as mdzip-core. The package was renamed to MDZip.Core starting with version 1.4.0 to match the MDZip.* NuGet ID scheme; mdzip-core is deprecated but remains listed for back-compat.

MDZip.Core provides APIs to:

  • create .mdz archives from folders or explicit file mappings
  • extract archives safely
  • list archive contents
  • read manifest.json
  • resolve the archive entry point
  • validate archives against path and manifest rules

Package Info

  • Package ID: MDZip.Core
  • Target frameworks: .NET 8, .NET 10
  • Output assembly: MDZip.Core.dll
  • Main namespace: MDZip.Core

Installation (NuGet.org)

Install the package from NuGet.org:

dotnet add package MDZip.Core

Quick Start

using MDZip.Core;
using MDZip.Core.Models;

// Create from a directory
MdzArchive.Create(
    outputPath: "book.mdz",
    sourceDirectory: "content",
    manifest: new Manifest
    {
        Title = "My Document",
        EntryPoint = "index.md"
    }); // spec.version, mode and timestamps are filled in

// Validate
var result = MdzArchive.Validate("book.mdz");
Console.WriteLine(result.IsValid);

// List entries
var files = MdzArchive.List("book.mdz");

// Add or replace a file in-place
MdzArchive.AddFile("book.mdz", "assets/notes.txt", "local-notes.txt");

// Remove a file in-place
MdzArchive.RemoveFile("book.mdz", "assets/old-image.png");

// Extract
MdzArchive.Extract("book.mdz", "out");

Public API

MdzArchive:

  • Create(string outputPath, string sourceDirectory, Manifest? manifest = null)
  • CreateFromFiles(string outputPath, IEnumerable<(string ArchivePath, string LocalPath)> files, Manifest? manifest = null)
  • AddFile(string archivePath, string archiveEntryPath, string localFilePath)
  • RemoveFile(string archivePath, string archiveEntryPath)
  • Extract(string archivePath, string destinationDirectory)
  • List(string archivePath)
  • ListDetailed(string archivePath)
  • ReadManifest(string archivePath)
  • ResolveEntryPoint(string archivePath)
  • Validate(string archivePath)

Additional types:

  • ValidationResult
  • ArchiveEntry
  • PathValidator
  • Manifest, ManifestSpec, ManifestAuthor, ManifestProducer, ManifestAgent, ManifestFile

Spec 1.2.0 behaviour

Version 2.0.0 implements MDZip spec 1.2.0 and runs its shared fixtures (tests/mdzip-core.Tests/Fixtures, synced with mdzip-spec/tools/sync-fixtures.mjs --ref v1.2.0). Things to know when upgrading from 1.x:

  • Paths are case-sensitive after Unicode NFC normalization (§5.4.1): Index.md no longer finds index.md. MdzArchive.FindCaseOnlyMatch suggests the near match after a failed lookup.
  • Every read checks the container first: encrypted entries (ERR_ZIP_ENCRYPTED), compression methods other than stored/DEFLATE (ERR_ZIP_INVALID), two entries equal after NFC (ERR_DUPLICATE_PATH) and a file that is also a directory (ERR_PATH_CONFLICT) throw.
  • Symbolic link entries are skipped and never followed: they're not listed, can't be read or extracted, are listed by ListSpecialFiles and reported by Validate. Mutations keep them unless dropSpecialFiles: true.
  • Entry point (§5.5): manifest.entryPoint (invalid → ERR_ENTRYPOINT_INVALID, missing file → ERR_ENTRYPOINT_MISSING, never a fallback); else root index.md; else the single root Markdown file once support files (README, AGENTS, LICENSE, CHANGELOG, CONTRIBUTING) are set aside. ResolveEntryPoint returns null when there is none; ResolveEntryPointStrict says why.
  • Manifests (§6.4): an invalid critical field (spec, spec.version, mode, entryPoint) is an error; an invalid descriptive field is ignored — left out of ReadManifest and reported as a Validate warning. null counts as a wrong type.
  • Producers always write manifest.json with spec.version 1.2.0, entryPoint and mode. Edits (AddFile, RemoveFile, UpdateFiles, UpdateManifest) keep every existing manifest field, nested unknown ones included, add a manifest to an archive without one, and throw ERR_ENTRYPOINT_CHANGED if a change would move the entry point.
  • Line endings: only Markdown files and manifest.json are normalized to LF when written (§12.2).
  • Errors are InvalidOperationExceptions whose message starts with the spec code; MdzSpec.ErrorCode(ex) reads it.
  • The rules are public too: MdzSpec (paths, entry point, manifest checks) and MdzLinks.ResolveLink (links inside, out of and into archives, §9.3–9.6).

Development

Build locally:

dotnet restore src/mdzip-core/mdzip-core.csproj
dotnet build src/mdzip-core/mdzip-core.csproj --configuration Release

Pack locally:

dotnet pack src/mdzip-core/mdzip-core.csproj --configuration Release -o out
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.1.0 112 10/26/2026
2.0.1 139 10/17/2026
2.0.0 131 10/15/2026
1.4.0 150 7/9/2026