A Useful Script For Kobo eReaders

Does this sound familiar? You open an article synced to your Kobo reader via Pocket and find that the text is almost unreadably small. You increase the font size, read the article, then flip over to the book you've been reading. Now the text is huge. You adjust the font size again, and the next time you open an article the text is back to miniscule.

It's a minor issue, maybe, but all of that fiddling with font sizes grates over time. After putting up with it for far too long, I finally resolved to find a solution. The breakthrough came with realizing that the problem was specific to sideloaded books — that is, books downloaded to my computer and transferred to the Kobo via USB or WiFi, rather than synced from Pocket, Overdrive, or the Kobo storefront. Now why would that be?

The answer is that the sideloaded texts were all .epub files. Kobo devices can read .epub files, of course, but they prefer to work with an extended version called .kepub — Kobo Epub. The .kepub format allows for a number of features, like highlight annotation and pop-up footnote previews, but the operative feature in this case is that the format allows the Kobo's user settings to override the font size in the book's embedded stylesheet. When displaying an .epub, the Kobo engine (Nickel) appears to add the custom font size to the font size set by the embedded stylesheet, which is why the text ended up being so large. Not the expected behavior! Covert the .epub to .kepub, and suddenly custom sizing works across the board.

Conversion can be handled in a couple of ways. Calibre, the Swiss Army knife of ebook managers, can do it. If you're comfortable using the command line, though, a more straightforward solution is kepubify, a succinct little package built for the sole purpose of making that specific conversion.

Using kepubify to convert books before importing them to my Kobo vastly improved the reading experience, but it potentially creates a lot of extra work. Converting books on a file-by-file basis would be tedious. If I didn't want to tidy up after every conversion, it would also effectively double the amount of storage space my ebooks took up on my computer. The obvious next step was to find some way to automate or streamline the process.

A few strategies sprang to mine, but after a bit of testing, the one I settled on was to convert the files directly onto the Kobo. I did that with the following shell script:

kepubify --output /path/to/Kobo/volume --update --copy .pdf /path/to/sideloading/folder

kepubify calls the package. --output sets the destination folder, so setting it to the path created when I mount my Kobo as an external volume directs the converted files to the device. --update tells the script to ignore previously converted files, so that only newly added books get converted. --copy .pdf ensures that also kepubify transfers any PDF files to the destination folder without attempting to convert them. And that last path is to a folder I set up as a staging ground for conversion. I saved that script (with actual paths rather than the placeholders here) in the parent folder alongside the staging folder, used chmod a+x scriptname to make it executable, and set it to execute into Terminal.

Now, when I want to sideload books onto my Kobo, I move the .epub files to the staging folder, connect the Kobo to my computer, and double-click that script file. The script copies the contents of the folder over to the Kobo, and in the process, converts any .epub files to .kepub in transit.