HTML Replacer Plugin for KOReader - A Walkthrough (Part 1)
Introduction
In this guide, I'll show you how the HTML Replacer plugin for KOReader works. We'll start with a simple book and walk through the process of modifying it.
[HR][/HR]
Accessing the Plugin
The plugin is available in the Style Tweaks menu under HTML Code → Content Tweaks.
Under the menu you'll see all the options available to you. The main two functions are
Add Replacement Rule and
Add Footnote Rule.
[HR][/HR]
Understanding Replacement Rules
Add Replacement Rule allows you to create a regular expression pattern and change the content from EPUB files using the replacement you specify. This uses Lua-flavored regular expressions - so check out the documentation for the actual rules, as not everything is supported.
Important: The replacements aren't only for visible text - they match against the entire HTML content of the EPUB file. So you can match against any HTML element in your book.
Example: Here's a rule to make chapter marks visible as H2 elements with classes:
You can add as many replacement rules as you want.
[HR][/HR]
Managing Your Rules
You can go into the Manage Rules tab to see which rules are active at any time. The way this plugin works is by actually replacing the content - taking the user's EPUB file and replacing it with a newly generated one. So changes don't happen in real time.
As you add more and more rules, they'll be made available in the menu:
By clicking on any rule under Manage Rules, you're able to disable or edit the rules as desired:
[HR][/HR]
A Simple Example: Making "New Terra" Uppercase
Let's look at a simple rule that makes the word "new terra" into all capital letters:
If I exit the menu now, I will not see any changes in the book itself:
[HR][/HR]
Applying Your Rules: Reload with Replacements
In order for these changes to take effect, I need to hit
Reload with Replacements in the menu:
After pressing Reload with Replacements, you'll be presented with a temporary version of the book to review. In this example, we can see that the changes have applied successfully:
[HR][/HR]
Where Modified Books Are Stored
Modified books are created under a specific folder location - under the KOReader installation folder in
HTML_Replacer_cache:
[HR][/HR]
Making Changes Permanent: Apply to Original
Once you're satisfied with the preview, you can make the changes permanent:
When you accept, the newly generated EPUB file will replace the original, preserving all the metadata and style changes:
[HR][/HR]
Important: Disable Rules After Applying
It is recommended that you disable the rules that you've previously applied.
Why? Because the rules will apply at every reload operation, and they'll apply on the modified version of the book. So if you don't have an inclusive or exclusive rule, it may apply over and over and over again. It's a good idea to disable rules that you know have already been applied to the book.
The rules aren't removed because there's an option to revert the book to the original - and if you go back to the original, you have the option to apply the rules again.
[HR][/HR]
Reverting to Original
If I hit
Revert to Original, I'll get the original state of the EPUB book file as it was before my modifications:
See that? "New Terra" is now not in all capital letters, because I've reverted to the original.