From e579f68cf3412c5d4fb13a0037df7539313a59c2 Mon Sep 17 00:00:00 2001
From: hbrain <hbrain@piagent.local>
Date: Sat, 16 May 2026 08:07:44 +0000
Subject: [PATCH] Add README

---
 README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7b9dd1f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# Wallabag to Kindle
+
+Small Python utilities for exporting Wallabag articles as individual EPUB files and sending them to Kindle by email.
+
+## What is included
+
+- `wallabag_to_epub.py` — fetches articles from the Wallabag API and builds one EPUB per article.
+- `send_to_kindle.py` — emails EPUB/PDF/MOBI files to your Kindle address using SMTP.
+- `wallabag.conf.sample` — example Wallabag API configuration.
+- `mail.conf.sample` — example SMTP/Kindle email configuration.
+
+Generated files are written to `out/` by default. Local config files and generated state are intentionally ignored by git.
+
+## Requirements
+
+- Python 3.10+
+- A Wallabag account with API client credentials
+- An SMTP account that Amazon allows as an approved Kindle sender
+- Your Kindle email address, for example `name@kindle.com`
+
+No third-party Python packages are required; the scripts use the Python standard library.
+
+## Setup
+
+Clone the repository, then create local config files from the samples:
+
+```bash
+cp wallabag.conf.sample wallabag.conf
+cp mail.conf.sample mail.conf
+chmod 600 wallabag.conf mail.conf
+```
+
+Edit `wallabag.conf`:
+
+```ini
+WALLABAG_URL=https://wallabag.example.com
+CLIENT_ID=your-wallabag-client-id
+CLIENT_SECRET=your-wallabag-client-secret
+USERNAME=your-wallabag-username
+PASSWORD=your-wallabag-password
+```
+
+Edit `mail.conf`:
+
+```ini
+SMTP_HOST=smtp.example.com
+SMTP_PORT=465
+SMTP_USER=user@example.com
+SMTP_PASS=your-smtp-password-or-app-password
+SMTP_SENDER=user@example.com
+KINDLE_EMAIL=your-kindle-address@kindle.com
+```
+
+In your Amazon Kindle settings, make sure `SMTP_SENDER` is listed as an approved personal document email address.
+
+## Export Wallabag articles to EPUB
+
+Export the latest unread articles:
+
+```bash
+./wallabag_to_epub.py --limit 10
+```
+
+This creates `.epub` files in `out/` and records downloaded articles in `wallabag_downloaded.json`, so future runs skip articles that were already exported.
+
+Useful options:
+
+```bash
+./wallabag_to_epub.py --limit 5 --starred          # only starred articles
+./wallabag_to_epub.py --limit 5 --all              # include archived/read articles
+./wallabag_to_epub.py --limit 1 --output article.epub
+./wallabag_to_epub.py --limit 10 --archive         # archive in Wallabag after successful export
+./wallabag_to_epub.py --redownload                 # ignore the downloaded DB
+```
+
+## Send EPUBs to Kindle
+
+Send all EPUB files from `out/`:
+
+```bash
+./send_to_kindle.py
+```
+
+Send a single file:
+
+```bash
+./send_to_kindle.py out/example.epub
+```
+
+After an email is sent successfully, `send_to_kindle.py` deletes the sent local file from `out/`.
+
+Useful options:
+
+```bash
+./send_to_kindle.py --max-attachments 10
+./send_to_kindle.py --config /path/to/mail.conf out/example.epub
+```
+
+## Typical workflow
+
+```bash
+./wallabag_to_epub.py --limit 10 --archive
+./send_to_kindle.py
+```
+
+This exports up to 10 new unread Wallabag articles, archives them in Wallabag, sends the resulting EPUBs to Kindle, and removes the sent EPUB files locally.
+
+## Notes
+
+- EPUB images are downloaded and embedded when possible.
+- EPUB metadata and attachment filenames use readable article titles so Kindle displays nicer document names.
+- `wallabag.conf`, `mail.conf`, `.git.env`, `out/`, and `wallabag_downloaded.json` are ignored because they may contain secrets or local state.