MDZip.Core
2.0.1
Prefix Reserved
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
<PackageReference Include="MDZip.Core" Version="2.0.1" />
<PackageVersion Include="MDZip.Core" Version="2.0.1" />
<PackageReference Include="MDZip.Core" />
paket add MDZip.Core --version 2.0.1
#r "nuget: MDZip.Core, 2.0.1"
#:package MDZip.Core@2.0.1
#addin nuget:?package=MDZip.Core&version=2.0.1
#tool nuget:?package=MDZip.Core&version=2.0.1
MDZip.Core
Core .NET library for working with .mdz archives.
Formerly published as
mdzip-core. The package was renamed toMDZip.Corestarting with version 1.4.0 to match theMDZip.*NuGet ID scheme;mdzip-coreis deprecated but remains listed for back-compat.
MDZip.Core provides APIs to:
- create
.mdzarchives 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:
ValidationResultArchiveEntryPathValidatorManifest,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.mdno longer findsindex.md.MdzArchive.FindCaseOnlyMatchsuggests 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
ListSpecialFilesand reported byValidate. Mutations keep them unlessdropSpecialFiles: true. - Entry point (§5.5):
manifest.entryPoint(invalid →ERR_ENTRYPOINT_INVALID, missing file →ERR_ENTRYPOINT_MISSING, never a fallback); else rootindex.md; else the single root Markdown file once support files (README, AGENTS, LICENSE, CHANGELOG, CONTRIBUTING) are set aside.ResolveEntryPointreturns null when there is none;ResolveEntryPointStrictsays why. - Manifests (§6.4): an invalid critical field (
spec,spec.version,mode,entryPoint) is an error; an invalid descriptive field is ignored — left out ofReadManifestand reported as aValidatewarning.nullcounts as a wrong type. - Producers always write
manifest.jsonwithspec.version1.2.0,entryPointandmode. Edits (AddFile,RemoveFile,UpdateFiles,UpdateManifest) keep every existing manifest field, nested unknown ones included, add a manifest to an archive without one, and throwERR_ENTRYPOINT_CHANGEDif a change would move the entry point. - Line endings: only Markdown files and
manifest.jsonare 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) andMdzLinks.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 | Versions 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. |
-
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.