KOReader Web Fiction Downloaders

KOReader plugins for downloading web fiction as EPUB files for offline reading.

Plugins

Royal Road Downloader (royalroad.koplugin)

Downloads stories from Royal Road as EPUB files.

AO3 Downloader (ao3.koplugin)

Downloads works from Archive of Our Own as EPUB files.

Features

• Download complete stories/works as EPUB files
• Simple input: just enter the fiction/work ID
• Configurable download directory
• Rate limiting to respect server limits
• Real-time progress tracking with elapsed time and ETA
• Detailed logging for debugging
• Automatic EPUB generation with proper metadata

Installation

1. Copy the desired plugin directory to your KOReader plugins folder:

   • Kobo/Kindle: /mnt/onboard/.adds/koreader/plugins/
   • Android: /sdcard/koreader/plugins/
   • macOS: ~/Library/Application Support/koreader/plugins/
   • Linux: ~/.config/koreader/plugins/

2. Restart KOReader

3. The plugin will appear in your tools menu

Quick Install (macOS)

./install-plugin.sh

Usage

Royal Road

1. Find a story on Royal Road (e.g., https://www.royalroad.com/fiction/21220/mother-of-learning)
2. Note the fiction ID from the URL (in this example: 21220)
3. In KOReader: Tools → Royal Road → Download story
4. Enter the fiction ID and tap Download
5. The EPUB will be saved to {KOReader}/royalroad/StoryTitle_ID.epub

AO3

1. Find a work on AO3 (e.g., https://archiveofourown.org/works/52206136)
2. Note the work ID from the URL (in this example: 52206136)
3. In KOReader: Tools → AO3 → Download work
4. Enter the work ID and tap Download
5. The EPUB will be saved to {KOReader}/ao3/WorkTitle_ID.epub

Configuration

Access settings via Menu → Tools → [Plugin Name] → Settings:

• Download directory: Where to save EPUB files
• Rate limit delay: Seconds between chapter downloads
  • Royal Road default: 1.5s
  • AO3 default: 5.0s (required by AO3 Terms of Service)

Finding IDs

The ID is the number in the URL:

Royal Road:

• https://www.royalroad.com/fiction/21220/mother-of-learning → ID is 21220

AO3:

• https://archiveofourown.org/works/52206136 → ID is 52206136

Limitations

• No official APIs - uses HTML scraping (may break if sites change)
• Cannot download paywalled/advanced chapters (Royal Road)
• Cannot download restricted/logged-in-only works (AO3)
• Large stories may take a while to download
• No resume functionality - interrupted downloads must restart

Development

See CLAUDE.md for development details and architecture information. See TESTING.md for local testing instructions.

License

These are unofficial plugins and are not affiliated with Royal Road, Archive of Our Own, or KOReader. Use responsibly and respect each site's terms of service.