1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0a5ea18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# ziglang-docs-epub
+
+Turns the [Zig language reference](https://ziglang.org/documentation/) into an
+**EPUB**, one per Zig version. CI runs it on a schedule and commits the resulting
+`.epub` files back into [`epubs/`](epubs/).
+
+## Why
+
+The reference ships as a single self-contained HTML page. This tool repackages it
+as a standards-compliant EPUB3 so you can read it offline in any e-reader.
+
+## How it works
+
+Four decoupled concerns, each a small module that does one thing:
+
+| Module        | Responsibility                                            |
+| ------------- | --------------------------------------------------------- |
+| `index.zig`   | discover versions + docs URLs from `download/index.json`  |
+| `fetch.zig`   | HTTP GET via `std.http.Client`                            |
+| `html.zig`    | transform the page HTML5 → well-formed XHTML5             |
+| `epub.zig`    | assemble the EPUB3 container                              |
+| `zip.zig`     | minimal, reproducible ZIP writer (stored entries)         |
+
+No external runtime dependencies — Zig's standard library provides HTTP and
+CRC32. EPUB entries are stored uncompressed (Zig 0.15.2's std deflate
+*compressor* is unfinished), which keeps the writer trivial and fully
+spec-compliant at the cost of larger files. Output is **byte-for-byte
+reproducible** (fixed ZIP timestamps), so CI only commits when the upstream docs
+actually change.
+
+## Usage
+
+Requires **Zig 0.15.2**.
+
+```sh
+zig build run            # build every version that has docs
+zig build run -- 0.15.2  # build only specific version(s)
+zig build test           # run unit tests
+```
+
+EPUBs land in `epubs/zig-<version>.epub`.
+
+## Continuous integration
+
+`.forgejo/workflows/build-epubs.yml` runs on [Codeberg](https://codeberg.org)
+(Forgejo Actions): daily, on push to `main`, and on manual dispatch. It installs
+Zig, runs the tool, and commits any changed EPUBs with `[skip ci]`.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).
+