ZimZipper

Package a folder (or a .zip) of Markdown / plain-text files — with images and LaTeX formulas — into one self-contained, offline, full-text-searchable ZIM archive you can read anywhere with Kiwix.

中文说明

What it does

• Walks a directory (or extracts a .zip) and collects every .md, .markdown and .txt file.
• Renders LaTeX ($...$, $$...$$, \(...\), \[...\]) to KaTeX HTML at build time, bundling KaTeX's CSS and fonts into the archive — so math displays correctly in Kiwix without JavaScript.
• Embeds images (and other local assets) preserving the original directory layout, so relative links keep working.
• Rewrites internal .md / .txt links to .html.
• Generates an index page and standard ZIM metadata.
• Builds an optional full-text search index (Xapian), so readers can search the content offline.

What it does NOT do

• No incremental update inside a ZIM — the format is immutable; rebuild the archive when sources change (the whole pipeline is one command, so rebuilding is cheap to script).
• No OCR — it packages text you already have, it does not turn scans into text.
• No HTML scraping / crawling — point it at a local directory or .zip.
• No .docx / .pdf ingestion — convert those to Markdown first.

Requirements

• Python 3.9+
• Node.js (for the bundled KaTeX renderer). If node is missing, math is left as raw LaTeX and everything else still works.
• Python packages: libzim, markdown (installed automatically).

Installation

# From PyPI
pip install zimzipper

# From source
git clone https://github.com/CodeOfMe/ZimZipper.git
cd ZimZipper
pip install -e .

Quick Start

# Package a folder of notes
zimzipper build ./notes -o notes.zim

# Package a zip; set title and language
zimzipper build ./book.zip -o book.zim --title "My Book" --lang zho

# Skip the full-text index (faster, smaller)
zimzipper build ./notes -o notes.zim --no-fulltext

# Inspect an existing archive
zimzipper info notes.zim

Copy the resulting .zim to your phone and open it in the Kiwix app.

Usage

CLI

zimzipper [-V] [-v] [-o OUTPUT] [--json] [-q] <command> ...

Commands:
  build <src> [-o OUT.zim] [--title T] [--lang zho] [--no-fulltext] [--node node]
  info  <path.zim>

Python API

Every function returns a ToolResult, so you never need try/except.

from zimzipper import build_zim, inspect_zim

r = build_zim(src="./notes", out="notes.zim", title="My Notes", lang="zho")
print(r.success)          # True
print(r.data["pages"])    # number of documents
print(r.data["images"])   # number of embedded assets
print(r.data["size"])     # bytes

info = inspect_zim(path="notes.zim")
print(info.data["entries"])

Agent Integration (OpenAI Function Calling)

from zimzipper.tools import TOOLS, dispatch

# Pass TOOLS to your LLM's function-calling API
result = dispatch("zimzipper_build", {"src": "/data/notes", "out": "/data/notes.zim"})
print(result["success"])  # True

How it works

directory / .zip
      │  walk  (skip __MACOSX, .DS_Store, ._*)
      ▼
  .md / .txt ──► extract math ──► KaTeX (Node, batched) ──► HTML placeholders
      │                                                          │
      │            markdown -> HTML  ◄── substitute placeholders ─┘
      ▼
  pages + referenced images + katex.min.css & fonts
      ▼
  libzim Creator ──► single .zim  (optional Xapian full-text index)

Development

pip install -e ".[dev]"
pytest -q
ruff check zimzipper/
python -m build          # sdist + wheel

License

GPL-3.0-or-later.