The Settings card is an overlay modal in Storefront accessible by tapping the Gear icon (⚙️) in the top-right toolbar. It provides a centralized location to manage catalog sources, caching, GitHub API configuration, search filtering, and plugin updates.

1. Open Storefront from KOReader (Tools → Storefront).
2. Tap the Gear icon (⚙️) located on the right side of the header toolbar.
3. The Settings overlay card will appear.

Settings

The card is organized into four distinct sections:

Controls how Storefront retrieves metadata, manages cached content, and cleans local storage.

• Catalog Source
  • Values: Storefront (default catalog) or Direct GitHub API.
  • Behavior: Tapping toggles between Storefront's catalog (updated hourly for fast loading) and live GitHub API search (which can hit rate limits or require a PAT).
• Refresh Cache
  • Values: Shows the timestamp of when catalog metadata was last fetched (e.g., 2026年07月27日 10:30 or 10:30pm, adhering to KOReader's 12-hour or 24-hour clock settings), or Never.
  • Behavior: Tapping immediately closes the Settings card and triggers a manual refresh of the catalog cache from the active source.
• Manage / Clear Cache
  • Behavior: Opens the granular cache management sub-dialog allowing you to see disk usage and selectively clear:
    • README files & images: Cached markdown documentation and embedded images for plugins and patches.
    • Wiki pages & images: Locally cached wiki articles.
    • Screensaver thumbnails: Downloaded thumbnail previews from the screensavers catalog.
    • All Caches: 1-tap removal of all cached markdown, wiki articles, and image thumbnails to free up device storage.

Configures search indexing behavior and GitHub API authentication.

• Include 0-star forks
  • Values: Checkbox (☑ enabled / ☐ disabled).
  • Behavior: Tapping toggles whether repository forks with zero stars are included in search and category list views. When toggled, the setting is saved to Storefront.lua and the active repository cache is cleared to update the visible list immediately.
• GitHub Token
  • Values: Configured ✓ or Not set.
  • Behavior: Tapping opens a dialog where you can enter or clear a GitHub Personal Access Token (PAT classic, ghp_...).
    • Save: Saves the PAT to boost API rate limits (from 60 to 5,000 requests/hour) and displays a confirmation toast (GitHub token saved.).
    • Clear: Removes the existing token.
    • Cancel: Closes the input dialog without changes.

Provides one-tap access to KOReader sleep-screen wallpaper configuration directly within Storefront.

• Screensaver mode
  • Values: Shows the currently active mode summary, such as Single (filename.png), Shuffle (12), Book Cover, Reading Progress, or Blank.
  • Behavior: Tapping opens the dedicated Screensaver Settings dialog.

Screensaver Settings

• Mode Selection:
  • Single Wallpaper: Select an individual wallpaper from your downloaded collection to show on sleep.
  • Folder Shuffle: Randomly cycles through all wallpapers in your screensaver collection on each sleep event.
  • Book Cover: Automatically extracts and displays the cover of your current book.
  • Reading Progress / Summary: Displays reading statistics, current page, and book progress.
• Display Adjustments:
  • Border Fill / Background: Cycle between Black Fill, White Fill, or No Fill (Transparent overlay).
  • Reading Progress Banner Overlay: Enable/disable the progress overlay bar across your wallpaper.
  • Stretch Image: Scale wallpapers to cover the full dimensions of your e-reader display.
  • Invert Colors: Invert dark/light tones for custom e-ink contrast or night reading.

Displays plugin metadata and opens the dedicated About Storefront sub-dialog to manage self-updates.

• About Storefront
  • Values: Current Storefront version (e.g., v1.0.0).
  • Behavior: Tapping opens the About Storefront dialog.
• Update Channel
  • Values: Stable or Beta.
  • Behavior: Tapping opens the About Storefront dialog where you can toggle your update channel preference.

Opening About Storefront provides access to:

• Version & Author Details: Displays the installed plugin version and author information (ultimatejimmy).
• Update Channel Toggle: Switch between Stable (recommended) and Beta release channels. Channel choices are saved to Storefront_channel.lua.
• Check for Updates: Manually query GitHub for Storefront updates.
  • If a newer release is found on your selected channel, Storefront opens the release details dialog showing changelogs and a 1-tap install option.
  • If you are already up to date, a notification toast confirms your current version.

• Close Button: Tap the Close button at the bottom of the card.
• Hardware Back Key: On devices with physical buttons or e-ink navigation bars, pressing the Back button closes the Settings overlay card.