Metadata-Version: 2.4
Name: zimzipper
Version: 0.0.2
Summary: Package Markdown/text collections (with images and LaTeX) into an offline, searchable ZIM archive for Kiwix
Author-email: akino <6130092+cycleuser@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/CodeOfMe/ZimZipper
Project-URL: Repository, https://github.com/CodeOfMe/ZimZipper
Project-URL: Documentation, https://github.com/CodeOfMe/ZimZipper#readme
Project-URL: Changelog, https://github.com/CodeOfMe/ZimZipper/releases
Keywords: zim,kiwix,offline,markdown,latex,katex,documentation,archive
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Text Processing :: Indexing
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: libzim>=3.0
Requires-Dist: markdown>=3.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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](https://www.kiwix.org/).

[中文说明](README_CN.md)

## 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

```bash
# From PyPI
pip install zimzipper

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

## Quick Start

```bash
# 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`.

```python
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)

```python
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

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

## License

GPL-3.0-or-later.
