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
    {
        Spec = new ManifestSpec { Name = "markdownzip-spec", Version = "1.1.0-draft" },
        Title = "My Document",
        EntryPoint = "index.md"
    });

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

Notes on Validation Behavior

• Entry paths are validated for traversal attempts and OS-reserved characters.
• manifest.json is optional, but if present it is parsed and validated.
• Supported manifest spec.version major version is 1 (when present).
• Entry point resolution order:

1. manifest.entryPoint (must reference a .md or .markdown file)
2. root index.md
3. exactly one root markdown file (.md or .markdown)

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