Table of Contents
Changelog
- 2026-03-07
- Initial publication
Preface
I’ve been eyeing the XTeink X4 for awhile now but the whole ’no book metadata browser’ gave me significant pause for quite some time. Historically I’ve used readers like the Kobo Clara HD, Moon+ Reader Pro and Librera Reader which provide me a good way of viewing books by tags, series and similar metadata which I rely on to filter my ’to read’ list.
I’ve come to use Librera combined with Wallabag for my general reading needs. They work quite well, are fully open source and I don’t need the Play Store to install the apps on my device, I can use Obtainium instead.
However, this requires an Android device (Boox Palma as of this writing) in order to be effective. It also means I have yet another device to maintain that may or may not receive long-term security updates, etc. An Android device will also fall into the realm of ‘wholly unsupported’ at some point. Usually within a year or three of purchase.
On the other hand, the XTeink X4 is a mini device, has simple firmware, simple electronics and is a low upkeep device that will likely have a support window far longer than any Android device.
I finally broke down and bought one (more on this device later) because it appears to check the important boxes: simple hardware, community support, OSS firmware, long term support window, low upkeep.
This purchase also forced me to dive head long into re-thinking how I approach reading.
KOReader
Failing
I’ve known about KOReader for a very, very long time. Long enough that I tried using it on a Kobo Clara HD when it was still ’the best device’ to buy. I’ve tried it on many different Android devices, Windows and Linux. I’ve always failed to be able to make the jump.
I always failed because it uses a standard filesystem view to view book content. You can kind of sort of get metadata browsing to work but the way to do that is cumbersome and just annoying to my brain. You really do want (need?) to use the standard filesystem browser for opening reading material with KOReader if you want to avoid extra steps, hassles and/or frustrations.
This is the same problem the XTeink X4 brings to bear which is helpful as I am able to use KOReader to experiment and work out a lot of the workflow changes I need to make to be able to use the XTeink X4 effectively.
Problem Solving
Given I bought the XTeink X4, you’d be right to assume I figured it out. After years of struggling and I figured out what needed doing.
🎉 Much excitement and a minor amount of revelry was had. 🎉
The trick was realizing I dig through my library in a very predictable fashion:
- If I want to read a book in a series: I go looking for the series then find the book number in the series so I can continue reading the series.
- If I want to read any book that’s not part of a series: I go looking based on book title.
Another important fact is that I use Calibre on a level that can be called ‘religious’ as it’s a really good metadata manager, library manager and a hell of a lot more. I manage all tagging, reading list, reading goal, etc etc etc within Calibre and it forms my ‘source of truth’. I can say more but this post is about KOReader, not Calibre.
Given these realizations I tried re-thinking the file names of books exported from Calibre and realized: this was the fix I needed. Seriously: I adjusted the book file naming and… I no longer get frustrated or annoyed with KOReader when it comes to finding content to read.
File Naming
For file naming, I set the following Preferences in Calibre.
Preferences -> Saving books to disk and Sending books to device -> Save template -> {series}{series_index:0>3s| - | -}{title}-{author}
That last bit is the file name layout that actually works for my brain. I can now go looking by series, by book title and similar with ease.
I now see the book series then number (if present) then title then author. Exactly the sort of order I think in for finding content to read.
Problem. Solved.
Going Further
Once I had solved the file name problem with KOReader a lot snapped into place very quickly.
Reading List / Acively Reading
I continue to use Calibre to manage my reading list along with The Story Graph to a lesser degree. I track tags in Calibre, I track reading goals in Calibre and so much more.
What’s nice is I have a habit of looking to Calibre as my source of truth and for surfacing anywhere from 5 - 10 books I want to have as priority reads; books that I want to read before others. I use Calibre to build the list then I open the files in KOReader and use its history tracking as a kind of ‘bookmark’. I can use the collections feature of KOReader but the history feature is pretty universal across reading devices and I want to keep my approach as simple and as universal as possible.
Wallabag
KOReader includes a way to sync content with Wallabag. I skipped this. The reason is I use Wallabag on my phone and computer and use it as a place to catalog items from my RSS feeds and other links from around the internet. See here for full details on how my reading flow works for ’not books’.
There is one key Wallabag use case that deserves attention: long form articles. Non ’news’ articles that are at least 15 minute reads (usually more like 30 - 60 minute reads) I flag as ‘archived’ in Wallabag for reading when I have a solid block of time to focus. These articles I only read on eink devices such as the Boox Palma.
Given I have a XTeink X4 on order and KOReader in the mix, I now export these articles as epub from Wallabag and put them in an ‘articles’ folder on my device for reading. I delete from Wallabag after I finish reading the epub and I’ll add to ArchiveBox at this time too if I feel I want to keep the text long-term. This may change though. Wallabag puts the source URL into the epub exports and that URL lets me avoid keeping the articles inside Wallabag until read. I’m still debating if I want to change my approach. Both keeping things in Wallabag until read or deleting in favor of just the epub are valid, it’s just a matter of figuring out which I prefer over time.
Zotero
I’ll come out and say it: reading PDF is a HUGE PAIN IN THE ASS on devices with less than 13.3" screens. Enough that I’ve gotten in the habit of just putting them inside Zotero for reading when I have the spoons to engage with more frustrating source material. In particular, this applies to science articles, research and a bit more. This also applies to things I intend to annotate heavily as I read.
The trouble is I don’t want to read at my desk, I don’t want to dig out the lapdock and I really just want to read comfortably on a small tablet screen (think Pixel Pro Fold or iPad mini).
KOReader solves this issue for me nicely. It has some amazing options for on the fly column adjustments, changing reading direction, rotation, zoom and more. With some deliberate practice and deliberate readings I was able to hone a workflow that lets me read PDF on my Pixel 9 Pro Fold. It’s not perfect but it’s certainly ‘good enough’.
There is a Zotero Sync Plugin for KOReader that’ll get you access to your full library stored in the Zotero web storage, which I use. I can now get access to my Zotero library within KOReader, read items and annotate items. This was a big deal for me and a major win. This Pull Request for the sync plugin even gets you 2 way sync. I’ve tested the pull request and… I’ve started using it instead of the main plugin for my Zotero reading needs.
Progress Sync
KOReader provides a plugin for syncing progress across devices and it’s self-hostable so you don’t have to use a public server. Additionally the XTeink X4 CrossPoint Firmware supports this sync service, inclusive of self-hosted deployments.
I went ahead and set this up as I can now do further KOReader experimentation and, when it arrives, sync progress to the XTeink X4 device.
This is a minor win for me but it is useful and practical, especially if you have multiple device setups.
Shared Content Storage
When dealing with mulitple devices I find it wise to have a shared content store. Normally, for me, this is some folder on a server somewhere that I sync to devices with rclone or Syncthingw or similar.
The trouble is that KOReader stores sdr folders with metadata and other key info it needs alongside the book files themselves. Thankfully they offer an option for changing where it stores these directories so I can now use a single content storage area for sync to all my devices.
Much like progress sync, this is a minor win but it is useful and practicle when you have mulitple device setups.
Custom Plugins
Column Number Selection
One annoyance I had with KOReader when working with PDF’s is that I could not assign mulitple column number options to a gesture. Because I work with PDF’s that have 1, 2, 3 and more columns, I wanted a way to quickly pick the number via a gesture. Due to the way KOReader implemented gestures and column number selection you cannot do this natively.
Thankfully my $dayJob is programming and I’m not shy when it comes to writing code to solve problems.
I wrote a small plugin that pops up a modal window so you can select a few common column numbers via gesture. No more tapping about: just make the gesture, select the number and move on.
Column Number Flip / Flop
Another annoyance I have with PDF files is a lot of multi-column PDF’s will change column number haphazardly throughout the text forcing you to jump between mulitple column values. Thankfully this is usually a flip/flop between single column and a consistent multi column number.
I wrote a 2nd custom plugin that lets you flip / flop between column numbers. It remembers the previous column number selection and simply flip / flops between the current value and prior value. You can kind of do this with KOReader but you have to specific explicit column numbers as gestures and it doesn’t have a native flip/flop operation.
This plugin is perfect for me as I can assign it to a gesture and quickly switch between single and multi column as I read which I’m forced to do far more frequently than I appreciate. No partial solution(s) needed.
My Config
I put togther my template config as a zip file for download. The linked file contains everything discussed above. It also has most of the plugins and fancy features turned off.
I like my reading environments focused and distraction free. I also like them to be consistent across devices.
This config provides these requirements and includes the Zotero Sync plugin 2 way sync pull request and my two column number plugins.
Feel free to use this config as a starting point for your own KOReader config.