OfficeIMO.Epub 3.0.3

OfficeIMO.Epub - EPUB extraction primitives

OfficeIMO.Epub provides reusable EPUB extraction primitives for modular OfficeIMO ingestion pipelines.

Install

dotnet add package OfficeIMO.Epub

Quick start

using OfficeIMO.Epub;

EpubDocument book = EpubDocument.Load("book.epub", new EpubReadOptions {
    PreferSpineOrder = true,
    IncludeRawHtml = false,
    MaxChapters = 100
});

Console.WriteLine(book.Title);

foreach (EpubChapter chapter in book.Chapters) {
    Console.WriteLine($"{chapter.Order}. {chapter.Title ?? chapter.Path}");
    Console.WriteLine(chapter.Text);
}

foreach (string warning in book.Warnings) {
    Console.WriteLine(warning);
}

Inspect bounded manifest resources

EpubDocument book = EpubDocument.Load("book.epub", new EpubReadOptions {
    IncludeResourceData = true,
    MaxResources = 500,
    MaxResourceBytes = 4L * 1024L * 1024L,
    MaxTotalResourceBytes = 32L * 1024L * 1024L
});

foreach (EpubResource resource in book.Resources) {
    Console.WriteLine($"{resource.Path} ({resource.MediaType}, {resource.LengthBytes} bytes)");
}

Manifest metadata is returned even when payload loading is disabled. Payload inclusion is opt-in and bounded per resource, in total, and by resource count; skipped payloads produce warnings.

Resolve chapter-relative references

EpubReference reference = EpubReference.Resolve(
    "EPUB/text/chapter.xhtml",
    "../images/cover%20art.png?size=large#front");

if (reference.Kind == EpubReferenceKind.Container) {
    Console.WriteLine(reference.ContainerPath);     // decoded ZIP lookup path
    Console.WriteLine(reference.ContainerUrlPath);  // URL-encoded link path
    Console.WriteLine(reference.ResolvedValue);     // encoded path plus query and fragment
}

Use the three-argument overload with chapter.BaseHref when resolving URLs found in chapter markup. Results distinguish container, external, embedded data, and invalid references without performing network or file-system access. ContainerPath remains case-sensitive and decoded for ZIP lookup, while ContainerUrlPath, Target, and ResolvedValue preserve a safe URL serialization. Root-relative references are resolved safely but marked non-conforming; file: URLs, ambiguous encoded separators, and paths that escape the container are rejected.

What it does

• Opens EPUB files as ZIP containers.
• Parses META-INF/container.xml and OPF package metadata.
• Follows OPF manifest and spine ordering.
• Reads hierarchical EPUB 3 navigation and EPUB 2 NCX labels when available.
• Extracts chapter text from XHTML/XML ASTs.
• Returns deterministic OPF manifest resources with optional bounded payloads.
• Resolves package, navigation, and content references through a shared typed URL contract.
• Emits structured diagnostics and warning messages for malformed, unsafe, encrypted, fixed-layout, or unreadable content.

Examples

Read metadata and spine-ordered chapters

using OfficeIMO.Epub;

EpubDocument book = EpubDocument.Load("handbook.epub", new EpubReadOptions {
    PreferSpineOrder = true,
    IncludeNonLinearSpineItems = false,
    MaxChapters = 50
});

Console.WriteLine(book.Title);
Console.WriteLine(book.Creator);
Console.WriteLine(book.Language);

foreach (var chapter in book.Chapters) {
    Console.WriteLine($"{chapter.Order}. {chapter.Title ?? chapter.Path}");
}

Keep raw chapter HTML when building a converter

using OfficeIMO.Epub;

var book = EpubDocument.Load("book.epub", new EpubReadOptions {
    IncludeRawHtml = true,
    MaxChapterBytes = 2L * 1024L * 1024L
});

foreach (var chapter in book.Chapters) {
    File.WriteAllText(
        $"chapter-{chapter.Order:000}.txt",
        chapter.Text);

    if (chapter.Html != null) {
        File.WriteAllText($"chapter-{chapter.Order:000}.xhtml", chapter.Html);
    }
}

Read from a stream and report warnings

using OfficeIMO.Epub;

await using var stream = File.OpenRead("upload.epub");
EpubDocument book = EpubDocument.Load(stream, new EpubReadOptions {
    FallbackToHtmlScan = true,
    DeterministicOrder = true
});

foreach (string warning in book.Warnings) {
    Console.WriteLine(warning);
}

Boundaries

• This package owns reusable EPUB parsing primitives.
• Reader integration belongs in OfficeIMO.Reader.Epub.
• The parser is read-only and does not attempt CSS layout, scripting, DRM, or package mutation.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0.
• License: MIT.
• Repository: EvotecIT/OfficeIMO

Dependency footprint

• External: None; no third-party EPUB engine.
• OfficeIMO: OfficeIMO.Drawing. Container, OPF, spine, navigation, chapter, and resource parsing are first-party.

See the complete OfficeIMO package map for related formats and conversion paths.