Add README.md

zulip/zulip_export/README.md

@@ -0,0 +1,90 @@
+# Zulip Export to Static HTML
+
+This project exports Zulip messages from a stream (optionally a single topic) into a static HTML viewer with local attachments.
+
+## Features
+
+- Exports stream messages (or one topic) and attachments via Zulip API.
+- Converts image attachments to WEBP (when Pillow is installed).
+- Renders other attachments as explicit download buttons.
+- Includes text search and date jump in the viewer.
+- Can embed all messages in HTML, or load from a generated JSON file.
+
+## Requirements
+
+- Python 3.9+
+- `requests`
+- Optional: `Pillow` (for WEBP conversion)
+
+Install dependencies:
+
+```bash
+pip install requests pillow
+```
+
+## Usage
+
+```bash
+python zulip_export.py \
+  --base-url https://zulip.yourcompany.com \
+  --email you@company.com \
+  --api-key YOUR_API_KEY \
+  --stream "My Stream"
+```
+
+Export a single topic:
+
+```bash
+python zulip_export.py \
+  --base-url https://zulip.yourcompany.com \
+  --email you@company.com \
+  --api-key YOUR_API_KEY \
+  --stream "My Stream" \
+  --topic "Some Topic"
+```
+
+## CLI options
+
+- `--base-url` Zulip base URL.
+- `--email` Zulip account email.
+- `--api-key` Zulip API key.
+- `--stream` Stream name.
+- `--topic` Optional topic filter.
+- `--out` Output folder (default: `zulip_export`).
+- `--chunk-size` Render batch size in the HTML app.
+- `--embed-html` Embed messages in generated HTML (default enabled).
+- `--no-embed-html` Load messages from generated JSON instead.
+- `--webp-quality` WEBP quality from 1 to 100.
+- `--webp-workers` Parallel workers for WEBP conversion.
+- `--delete-original-images` Delete `uploads_originalimages/` after a successful conversion pass where no message still depends on originals.
+
+## Output naming
+
+Output filenames are sanitized to contain only alphanumeric characters and underscores:
+
+- Full stream export:
+  - `<STREAM>.html`
+  - `<STREAM>.json`
+- Single topic export:
+  - `<STREAM>_<TOPIC>.html`
+  - `<STREAM>_<TOPIC>.json`
+
+Any non-alphanumeric characters in stream/topic names are replaced with `_`.
+
+## Output structure
+
+Example output folder:
+
+```text
+zulip_export/
+  <STREAM>.html or <STREAM>_<TOPIC>.html
+  <STREAM>.json or <STREAM>_<TOPIC>.json
+  uploads/
+  uploads_originalimages/
+  uploads_webp/
+```
+
+## Notes
+
+- If Pillow is not installed, images are not converted and original files are used.
+- For local `file://` viewing, some browsers may block JSON fetches. Use `--embed-html` (default) or serve the folder with a local HTTP server.