📚 Overview

Readeck Plugin for KOReader is a plugin that allows you to synchronize articles from a Readeck server directly to your KOReader-powered e-reader. Readeck is a simple yet powerful web application that lets you save web content you want to keep forever. This plugin brings that content to your E-ink screen for a focused, distraction-free reading experience.

🚧 Project Status

Functional but “Cozy” 🏠

This project started as a personal, self‑use plugin, rapidly prototyped with AI assistance (GitHub Copilot). Thanks to valuable feedback and contributions from the community, it has gradually grown into something useful for more people.

Source code is published at github.com/iceyear/readeck.koplugin under the MIT License.

The plugin is functional and actively used, but it may not work perfectly in every scenario. The implementation is being moved toward smaller Lua modules with tests and formatting/lint checks.

Due to limited personal time, my focus going forward will mainly be on maintenance, stability, and critical bug fixes.

That said, community involvement is very welcome:

• PRs are appreciated, whether for refactoring, bug fixes, or small improvements
• Feel free to open Feature Requests in the Issues — discussion and collaborative implementation are encouraged
• You are welcome to fork this project or reuse its ideas as a starting point (“reinventing the wheel” is totally fine here)

This is a cozy project, and I hope it can remain one — with the community’s help 💖

🌟 Features

• 🔄 Sync & Download: Download articles from your Readeck server to a dedicated folder on your KOReader device.
• 🏷️ Tag Filtering: Only download articles with a specific tag, ignore articles with certain tags, and auto-add tags to newly created bookmarks.
• ↕️ Sorting: Sort server articles by added/published date, duration, site name, or title.
• 🗄️ Completion Actions: Optionally archive or delete finished/100%-read articles in Readeck, and remove local files only after the server action succeeds.
• 🧾 History Cleanup: Optionally remove finished/fully-read Readeck documents from KOReader history.
• 🌐 Add to Readeck (with Queue): Add links from KOReader; if offline, links are stored in a queue and retried next time you’re online.
• 📝 Review → Tags: Write comma-separated tags in the Review field and send them back to Readeck as labels.
• ⭐ Star / Like Sync: Optionally mark entries as liked on Readeck based on your KOReader star rating threshold, and/or label entries with their star rating (e.g. 3-star).
• 📊 Reading Progress Sync (beta): Sync KOReader reading progress below 100% back to Readeck, and apply newer incomplete Readeck progress to local sidecars. Disabled by default.
• 🖍️ Highlight Sync: Merge Readeck annotations into KOReader highlights and export local KOReader highlights, notes, and mapped colors back to Readeck. The plugin reads /api/info and adapts newer annotation fields to the Readeck server version.
• 🕒 Metadata Sync: Set downloaded file timestamps from Readeck metadata and add estimated reading time as a KOReader keyword.
• 🔁 Periodic Sync (beta): Optionally let KOReader schedule recurring Readeck syncs while the app is running.
• ⚡ Cooperative Downloads: Download articles through a bounded async queue. Concurrency is configurable from 1 to 3 so slower devices can stay responsive.
• 🌍 Plugin i18n Fallbacks: Reuse KOReader gettext when available, then fall back to plugin-provided English/Chinese strings.

📥 Installation

1. Clone or download this repository.
2. Locate your KOReader plugins directory (usually koreader/plugins/).
3. Copy the readeck.koplugin folder into the plugins directory.
4. Restart KOReader completely (use Exit from the menu, then relaunch).

Compatibility warning: The refactored plugin settings are not fully compatible with very old experimental builds. If you upgrade from an early version and see odd sync or authentication behavior, clear the old readeck.lua plugin settings and configure the plugin again before filing a bug.

⚙️ Configuration

To use this plugin, you need:

1. A running Readeck server (learn more at readeck.org)
2. A dedicated download folder configured on your KOReader

Initial Setup

1. Go to Main Menu > Readeck > Settings > Configure Readeck server

2. Enter the server URL (without /api)

3. Choose one authentication method:

   • OAuth (Device Flow) (recommended for convenience; used when the server advertises OAuth support), or
   • API Token

4. Set a dedicated Download folder

5. (Optional) Configure:

   • Only download articles with tag
   • Sort articles by
   • Tags to ignore
   • Tags to add to new articles

🛠️ Usage Instructions

Downloading New Articles

1. Go to Main Menu > Readeck > Synchronize articles with server
2. Articles will be downloaded according to your tag filter / ignore settings

Tip: If Process completion actions when syncing is enabled, archiving/deleting in Readeck can be handled automatically during sync.

Marking Articles as Finished

When you finish reading an article:

1. Mark it as finished (e.g., set status to complete) and/or read it to 100%
2. Go to Main Menu > Readeck > Process finished/read articles
3. The plugin will apply your configured completion action, sync highlights first, and remove local files only after Readeck confirms the action

Adding Articles

When browsing the web:

1. Open a link in KOReader's browser
2. Select Add to Readeck from the external link menu

If you are offline:

1. The link will be added to a download queue
2. It will be retried automatically the next time you’re online (during sync)

Syncing Highlights

1. Open a downloaded Readeck article in KOReader
2. Go to Main Menu > Readeck > Sync current article highlights
3. Readeck annotations are imported into KOReader highlights, local KOReader highlights with supported notes/colors are uploaded to Readeck, and already linked annotations are incrementally updated both ways.

For linked highlights, Highlight update strategy defaults to merging local and remote note/color changes using the last synced state. You can also force Readeck overwrites KOReader or KOReader overwrites Readeck.

By default, remote-deleted highlights are preserved locally and may be restored to Readeck on the next sync. Set Remote-deleted highlights to Respect remote deletions if you prefer deleted Readeck annotations to stay local-only and not be re-uploaded.

Syncing Reading Progress

During sync, the plugin can send KOReader's local reading progress below 100% back to Readeck without archiving the article. It also applies newer incomplete Readeck read_progress values to KOReader sidecars when articles are downloaded or skipped because they already exist locally. Articles that are being processed by completion actions are handled by the archive/delete flow instead.

⚠️ Notes

• The download directory should be exclusively used by the Readeck plugin; existing files in it may be deleted
• Username/password login is no longer supported; use OAuth or an API token
• The Send review as tags option allows you to add tags while reading

🔧 Advanced Settings

Readeck Server / Authentication

• Configure Readeck server > Server URL: Set the base Readeck URL without /api
• Configure Readeck server > Readeck server features: Auto-detect /api/info, force modern Readeck 0.22.2+ annotation fields, or force legacy compatibility
• Authentication > Authorize with OAuth: Use device-flow OAuth login (with optional QR code)
• Authentication > Reset access token: Clear token so the plugin re-authenticates
• Authentication > Clear all cached tokens: Remove cached OAuth/token data
• Authentication > API token: Configure a Readeck API token

Readeck Client

• Download limits: Set the number of articles processed per sync and the download concurrency
• Experimental subprocess downloads: Try parallel downloads without KOReader's async HTTP looper. If this backend fails, the plugin disables it for the current run and retries with the blocking downloader.
• Network timeouts: Tune network timeouts for slow connections or large downloads
• Language: Follow KOReader's language, or force the plugin UI to English / Simplified Chinese
• Log level: Filter plugin logs (Info by default, Debug for troubleshooting)

Article Selection

• Download folder: Choose the KOReader folder used for downloaded articles
• Only download articles with tag: Only download entries with a specific label
• Sort articles by: Choose the server-side ordering (added/published/duration/site/title)
• Tags to ignore: Skip entries containing any of the specified tags
• Tags to add to new articles: Auto-label newly added bookmarks (including links added from KOReader)

Article Actions

• Process finished articles in Readeck: Process entries marked as finished
• Process 100% read articles in Readeck: Process entries that reached 100% progress
• Archive completion actions instead of deleting: Archive entries instead of permanently deleting them
• Process completion actions when syncing: Run completion actions automatically during sync
• Sync reading progress to Readeck (beta): Update Readeck's reading progress below 100% for local articles that remain on the device, and accept newer incomplete Readeck progress locally
• Remove local files missing from Readeck: Remove local files that no longer exist on the server
• Remove finished articles from history: Clean up KOReader history for completed entries
• Remove 100% read articles from history: Clean up history for fully read entries

Highlights / Periodic Sync

• Sync highlights before article sync: Export/import highlights before retrieving articles
• Sync highlights when closing a document: Sync the current Readeck article's highlights when closing it
• Periodic sync (beta): Enable a KOReader timer and choose the interval in minutes
• Highlight update strategy: Merge linked note/color edits, or force Readeck/KOReader to overwrite the other side
• Remote-deleted highlights: Choose whether deleted Readeck annotations should be restored from KOReader or kept local-only

Sync is paced for KOReader devices: article downloads can run with limited concurrency when a supported async backend is available, highlight sync before article sync is split across local files so progress can render, and the article-list request only uses KOReader's async HTTP client when its async looper is already active. Unsupported or failing backends safely fall back to the blocking request path. The sync progress popup can be dismissed, moved with KOReader's standard movable dialog gestures, and reopened from the Readeck menu while sync is still running.

Ratings And Review Tags

• “Like” entries in Readeck: Mark entries as liked based on your KOReader star rating threshold
• Label entries in Readeck with their star rating: Add labels like 1-star … 5-star
• Send review as tags: Treat comma-separated content in the KOReader Review field as tags and send them to Readeck

Development

• make deps
• make format-check
• make test
• make lint
• make koreader-smoke
• make koreader-network-smoke
• make koreader-build
• make koreader-runtime-smoke

make deps uses LuaRocks to install development tools from readeck-koplugin-dev-0.1-1.rockspec. The plugin itself does not depend on LuaRocks at runtime; it should keep using KOReader's bundled Lua modules and native libraries so it remains portable across Linux, Android, and e-reader builds.

make koreader-smoke always runs the fast KOReader-shaped stub smoke test. If a built KOReader emulator runtime exists at references/koreader/koreader-emulator-x86_64-pc-linux-gnu-debug/koreader, it also runs the real runtime probe with KOReader's own luajit, setupkoenv.lua, and unit-test bootstrap. Use make koreader-build first, or set KOREADER_DIR / KOREADER_BUILD_DIR when your KOReader checkout lives elsewhere.

make koreader-network-smoke starts a local mock Readeck HTTP server and drives the plugin through KOReader's runtime against real socket.http calls. It covers API-token auth, OAuth form endpoints, bookmark listing, EPUB download, and highlight sync/export conflict behavior without needing a public Readeck instance.

CI runs Stylua, Luacheck, Busted, mock Readeck API tests, the stub smoke test, and separate KOReader runtime/network smoke jobs on GitHub Actions.

🔍 Troubleshooting

• If downloads fail, double-check your server URL and authentication settings
• Ensure KOReader has active network access
• Verify that the download directory exists and is writable
• For advanced debugging, check crash.log or enable logcat on Android

🙏 Credits

• Based on wallabag2.koplugin by clach04
• KOReader — The best FOSS e-ink book reader
• Readeck — Making web content readable again

📄 License

This plugin is open source under the MIT License. Source repository: https://github.com/iceyear/readeck.koplugin.