Skip to content

zim-format.md

Latest commit

 

History

History
102 lines (75 loc) · 3.61 KB

zim-format.md

File metadata and controls

102 lines (75 loc) · 3.61 KB
Raw

ZIM File Format

Overview

ZIM (Zeno IMproved) is an open file format for storing Wiki content for offline use. It compresses web content (HTML, images, CSS, JavaScript) into a single highly-compressed archive file, enabling fast access without an internet connection.

File Structure

A ZIM file consists of:

  1. MIME Type List - Dictionary of all MIME types used in the archive
  2. URL Pointer List - Offsets to article directory entries
  3. Title Pointer List - Offsets for title-based access
  4. Cluster Offset List - Offsets to data clusters
  5. Directory Entries - Metadata for each article (URL, title, MIME type, cluster number)
  6. Clusters - Actual compressed data blocks

Header (80 bytes)

Offset Field Type Description
0 Magic Number uint16 0x043A (ZIM version)
4 Article Count uint32 Total number of entries
8 Cluster Count uint32 Number of data clusters
12 URL Pointer List Offset uint64 Start of URL pointers
20 Title Pointer List Offset uint64 Start of title pointers
28 Cluster Offset List Offset uint64 Start of cluster offsets
36 MIME List Offset uint64 Start of MIME types
44 Main Page uint32 Directory index of main page
48 Layout Page uint32 Directory index of layout page
52 Checksum Position uint64 Start of SHA-256 checksum

Namespaces

ZIM uses a single-character namespace prefix to organize content by type:

Namespace Content Examples
C Content (modern) /wikipedia_en_all_nopic/A/Page_Title.html
A Articles (legacy) Old ZIM format, same as C
I Images /wikipedia_en_all_nopic/I/en/thumb.jpg
J Text images /wikipedia_en_all_nopic/J/math_formula.svg
- Layout/Scripts /wikipedia_en_all_nopic/-/style.css
M Metadata /wikipedia_en_all_nopic/M/Title
X Reserved headers Internal ZIM structures

Namespace Usage in ZIM Reader

// Skip non-content resources in search results
if !strings.HasPrefix(url, "C/") && !strings.HasPrefix(url, "A/") {
    return false // Not an article
}

Directory Entries

Each directory entry contains:

Field Type Description
Offset int32 Offset within cluster (or -1 for redirects)
MIME Type uint16 Index into MIME type list
Redirect Target uint32 Directory index of redirect target
Namespace char Single character namespace identifier

Redirects

Redirect entries store:

  • Redirect Index: Points to the target directory entry
  • No data stored in clusters (offset is -1)

Used for:

  • Common misspellings
  • Alternative titles
  • Shortcut redirects
  • Disambiguation pages

Clusters

Clusters store compressed article data:

  • Compression: Zstandard (zstd), LZMA, or uncompressed
  • Blob Size: Variable, typically 1-100 KB per article
  • Access Pattern: Random access via directory entry offset

Content Access Pattern

  1. Parse URL namespace → extract directory index
  2. Lookup directory entry by index
  3. Read cluster number and blob offset from entry
  4. Seek to cluster offset via cluster offset list
  5. Decompress blob from cluster

Official Specification

See the OpenZIM Specification for complete format details, including compression algorithms, checksums, and extension mechanisms.

See Also