Packaging & Compressing the EPUB Archive

Technical Deep Dive & Specifications

The OCF Physical ZIP Container Rules

The W3C Open Container Format (OCF) defines the following immutable rules for packaging an .epub file:

1. ZIP Format: Must comply with the standard PKZip format (Info-ZIP 2.0+). No multi-volume archives, encryption headers at root, or proprietary ZIP64 extensions unless exceeding 4GB.
2. The mimetype File:
   • Must be the very first file in the ZIP archive.
   • Filename must be lowercase mimetype (no file extension).
   • Content must be the exact 20-character ASCII string: application/epub+zip.
   • Must NOT contain any trailing carriage returns, newlines, or whitespace (\r or \n).
   • Must NOT be compressed (Compression Method = 0 / Stored).
   • Must NOT have an extra field in its local file header.
3. Subsequent Payload: All other files (META-INF/container.xml, content documents, images, CSS) can and should be compressed using standard Deflate compression (Compression Method = 8).

Command-Line Packaging Recipes

1. Bash / macOS / Linux CLI (Two-Step Zip Recipe)

# Step 1: Add mimetype file with ZERO compression (-0) and NO extra attributes (-X)
zip -X0 my_book.epub mimetype

# Step 2: Add all remaining directories with maximum compression (-9), recursively (-r)
zip -r9 my_book.epub META-INF EPUB -x "*.DS_Store" -x "*Thumbs.db"

2. Cross-Platform Node.js Build Script (build-epub.js)

Using the popular archiver library ensures byte-perfect OCF compliance across Windows, macOS, and Linux:

const fs = require('fs');
const archiver = require('archiver');

const output = fs.createWriteStream('dist/publication.epub');
const archive = archiver('zip', { zlib: { level: 9 } });

output.on('close', () => {
  console.log(`[SUCCESS] EPUB created: ${archive.pointer()} total bytes.`);
});

archive.pipe(output);

// Step 1: Store mimetype UNCOMPRESSED at root
archive.append('application/epub+zip', { 
  name: 'mimetype', 
  store: true // store: true means 0% compression (Stored)
});

// Step 2: Add META-INF and content folders with full compression
archive.directory('src/META-INF/', 'META-INF');
archive.directory('src/EPUB/', 'EPUB');

archive.finalize();

Validating with the Official W3C epubcheck Tool

epubcheck is the authoritative validation tool used by Apple Books, Amazon KDP, Kobo, and Google Play Books before accepting submissions.

# Running epubcheck via Java CLI
java -jar epubcheck.jar my_book.epub

+-------------------------------------------------------------------------------+
|                         EPUBCHECK VALIDATION OUTPUT                           |
+-------------------------------------------------------------------------------+
| Validating against EPUB version 3.3 ...                                       |
| Validating OCF container packaging rules...                                   |
| Validating mimetype first entry (stored 0 bytes compression)... [PASSED]      |
| Validating META-INF/container.xml syntax... [PASSED]                          |
| Validating EPUB/package.opf against RelaxNG schema... [PASSED]                |
| Checking XHTML content well-formedness and entities... [PASSED]               |
| Checking navigation document (nav.xhtml)... [PASSED]                          |
|                                                                               |
| EpubCheck: No errors or warnings detected.                                    |
| Congratulations! Publication is 100% compliant and ready for distribution.   |
+-------------------------------------------------------------------------------+

Common epubcheck Error Codes Reference

💻 Interactive Code Playground

Starter Code: Deterministic PowerShell Packaging Script (Package-Epub.ps1)

Line-by-Line Code Breakdown

• Line 21 (ZipArchiveMode::Create): Opens an empty binary ZIP output stream.
• Line 24 ([CompressionLevel]::NoCompression): The critical instruction forcing .NET to store the mimetype file with 0% compression.
• Line 26 ($writer.Write("application/epub+zip")): Writes the exact 20-character string without appending a newline (Write-Line is avoided).
• Line 40 ([CompressionLevel]::Optimal): Applies standard Deflate compression level to all payload documents, stylesheets, and images.
• Line 36 (Skip hidden OS files): Filters out platform metadata files (.DS_Store, Thumbs.db) that pollute production e-books.

<#
.SYNOPSIS
  Deterministic EPUB 3 Packaging Script for Windows PowerShell
#>

param (
    [string]$SourceDir = ".\src",
    [string]$OutputFile = ".\dist\handbook.epub"
)

# Ensure output directory exists
$distDir = Split-Path $OutputFile
if (!(Test-Path $distDir)) {
    New-Item -ItemType Directory -Path $distDir -Force | Out-Null
}

# Remove existing target file if present
if (Test-Path $OutputFile) {
    Remove-Item $OutputFile -Force
}

# Load .NET Compression Assemblies
Add-Type -AssemblyName System.IO.Compression

# Step 1: Create new ZIP archive
$zipStream = [System.IO.File]::Open($OutputFile, [System.IO.FileMode]::Create)
$archive = New-Object System.IO.Compression.ZipArchive($zipStream, [System.IO.Compression.ZipArchiveMode]::Create)

try {
    # Step 2: Write UNCOMPRESSED mimetype entry
    $mimetypeEntry = $archive.CreateEntry("mimetype", [System.IO.Compression.CompressionLevel]::NoCompression)
    $writer = New-Object System.IO.StreamWriter($mimetypeEntry.Open(), [System.Text.Encoding]::ASCII)
    $writer.Write("application/epub+zip")
    $writer.Flush()
    $writer.Close()

    Write-Host "[OK] Mimetype entry stored uncompressed at byte 38." -ForegroundColor Green

    # Step 3: Helper function to recursively add directories with Optimal compression
    function Add-FolderToArchive($folderPath, $archivePrefix) {
        $items = Get-ChildItem -Path $folderPath -Recurse -File
        foreach ($file in $items) {
            # Skip hidden OS files
            if ($file.Name -eq ".DS_Store" -or $file.Name -eq "Thumbs.db") { continue }

            $relativePath = $file.FullName.Substring((Resolve-Path $folderPath).Path.Length + 1).Replace('\', '/')
            $entryPath = if ($archivePrefix) { "$archivePrefix/$relativePath" } else { $relativePath }

            $entry = $archive.CreateEntry($entryPath, [System.IO.Compression.CompressionLevel]::Optimal)
            $entryStream = $entry.Open()
            $fileStream = [System.IO.File]::OpenRead($file.FullName)
            $fileStream.CopyTo($entryStream)
            $fileStream.Close()
            $entryStream.Close()
        }
    }

    # Add META-INF and EPUB payloads
    Add-FolderToArchive "$SourceDir\META-INF" "META-INF"
    Add-FolderToArchive "$SourceDir\EPUB" "EPUB"

    Write-Host "[OK] Payload directories compressed and added." -ForegroundColor Green
}
finally {
    $archive.Dispose()
    $zipStream.Dispose()
}

Write-Host "[SUCCESS] Packaged EPUB 3: $OutputFile" -ForegroundColor Cyan