HTML Replacer plugin - Edit EPUB Content Directly on KOReader

[lumping-sugar66]

HTML Replacer - Edit EPUB Content Directly on Your Device

Why This Plugin?

You're reading an EPUB and notice issues - missing italics on book titles, typos, weird chapter dividers, or that annoying first-line formatting that CSS tweaks can't catch.

But you're in the middle of reading. You don't want to:

• Close the book
• Fire up Calibre on your computer
• Edit the EPUB
• Transfer it back
• Find where you were reading

This plugin lets you edit EPUBs directly on your device, right in the middle of reading. Apply regex replacements, preview the changes, and continue reading - all without leaving KOReader.

Features

• Book-specific regex replacement rules
• Preview changes before applying permanently
• Pattern checker to test your regex
• Backup & revert functionality
• Works entirely on-device, no computer needed

Quick Start

1. Install to

   koreader/plugins/htmlreplacer.koplugin/

2. Open an EPUB → Menu → Style tweaks → HTML content tweaks
3. Add rules (e.g.,

   <span>(.-)</span>

   →

   %1

   to remove spans)
4. Reload with Replacements to preview
5. Apply Changes when satisfied (backs up original)

Menu Navigation

Tap the top menu → Style tweaks → HTML content tweaks (first item in the Style tweaks submenu)

From there you'll see:

• Toggle Replacement Rules - Quick enable/disable
• Add New Rule - Create a new pattern
• Manage Rules - Edit/delete existing rules
• View Current Rules - See all rules for this book
• Reload with Replacements - Generate preview
• Apply Changes to Original - Make permanent (only when viewing preview)
• Revert to Original - Restore backup (only when backup exists)
• Clear Cache - Remove all cached previews

Example Patterns

-- Fix missing italics on book titles
"The Lord of the Rings"  →  <i>The Lord of the Rings</i>

-- Fix typos
" teh " → " the "

-- Change chapter dividers
"<hr.->"  →  <div class="divider">• • •</div>

-- Remove first-line formatting that CSS won't catch
">([A-Z ]{2,50})"  →  "><span class="makelowercase">%1"

-- Add missing emphasis
'([^']+)'  →  <em>'%1'</em>

Download

https://github.com/onatbas/htmlreplacer.koplugin

Important Notes & Disclaimers

1. Apply Overwrites Original EPUB
The "Apply Changes to Original" step permanently replaces your EPUB file. The original is backed up to

htmlreplacer_cache/originals/

The metadata should be unaffected but during preview you will lose your tweaks until Apply.
Apply also appends the book-specific style tweaks to the original metadata of the replaced book because in my case html tweaks and css tweaks often go hand in hand.

2. Revert Option Available
If you're reading a modified EPUB and want to go back, use "Revert to Original" to restore from the backup in the cache folder. Your rules are preserved even after reverting.

3. Don't Start Patterns with Wildcards!
Never start regex patterns with wildcards like .* or .- - this can overpower the CPU and hang your device. Always start with explicit matches, emphasize explicitness as much as possible:

• Good: <span class=".-">
• Bad: .span class=".-">

4. Use the "Check" Button!
Each rule has a "Check" button that shows you all matches and the before/after results. This will help prevent surprises, 0 matches and broken EPUBs.

5. Lua Patterns Are Different from Standard Regex
KOReader uses Lua patterns, not PCRE/standard regex:

• .- = non-greedy match (not .+? or .*?)
• .+ = greedy match
• %s = whitespace (not \s)
• %d = digit (not \d)
• Use % to escape special chars (not \)

Reference: https://www.lua.org/manual/5.1/manual.html#5.4.1

6. Tested On

• Kobo Aura Edition 2
• Kobo Clara 2E
• Kobo Clara Libra 2
• KOReader emulator

Installation

Setting up this plugin is easy. All you have to do is grab every file that you see under the code repository and put them under the plugins folder of your KOReader installation:



Then give KOReader a restart, and you should be good to go.

[HR][/HR]

Questions? Ask in this thread!

[nqk]

I tried this on Android and it crashed when I hit Reload with Replacements (I only had one rule)

Sent from my Pixel 7 Pro using Tapatalk

[lumping-sugar66]

Sorry to hear that. If you can share your replacement pattern info and even crash logs I could take a look for you.

[nqk]

Originally Posted by lumping-sugar66

Sorry to hear that. If you can share your replacement pattern info and even crash logs I could take a look for you.

The rule can't be simpler (as I was only testing)

"tôi lập tức" ==> "tôi lập tứcs"

I tapped on "check" (when the rule is added) and it crashed.

--------- beginning of system
11-13 13:39:16.653 I/DisplayManager( 3634): Choreographer implicitly registered for the refresh rate.
11-13 13:39:16.686 D/InsetsController( 3634): Setting requestedVisibleTypes to 498 (was 503)
11-13 13:39:16.689 W/ActivityThread( 3634): Activity top position already set to onTop=false
11-13 13:39:16.734 D/InsetsController( 3634): hide(ime())
11-13 13:39:16.741 D/InsetsController( 3634): Setting requestedVisibleTypes to 496 (was 498)
11-13 14:07:24.302 D/InsetsController( 3634): hide(ime())
--------- beginning of main
11-13 14:10:51.229 D/ViewRootImpl( 3634): Skipping stats log for color mode
11-13 14:10:51.229 V/NativeGlue( 3634): Start: 0xb4000077c6ef4170
11-13 14:10:51.230 V/KOReader( 3634): input event => type: 4 (EV_MSC), code: 10 (nil), value: 1, time: 9709.420975
11-13 14:10:51.230 V/KOReader( 3634): Android application event 10
11-13 14:10:51.231 V/NativeGlue( 3634): Resume: 0xb4000077c6ef4170
11-13 14:10:51.724 D/InsetsController( 3634): hide(ime())

Sent from my Pixel 7 Pro using Tapatalk

[lumping-sugar66]

Thank you for the logs. It looks like the zip/unzip and browser management was unfriendly for Android devices, although your pattern worked both on my kobo and the emulator. Good news though, my good friend ChatGPT and I seem to have found a better way to handle it for Android, too. Just pushed the changes to the repository, along with a significant amount of additional logs. If you can try this out and let me know, I'd appreciate it.

[nqk]

Originally Posted by lumping-sugar66

Thank you for the logs. It looks like the zip/unzip and browser management was unfriendly for Android devices, although your pattern worked both on my kobo and the emulator. Good news though, my good friend ChatGPT and I seem to have found a better way to handle it for Android, too. Just pushed the changes to the repository, along with a significant amount of additional logs. If you can try this out and let me know, I'd appreciate it.

Unfortunately it still crashed.

--------- beginning of system
11-14 09:28:55.505 I/DisplayManager(26328): Choreographer implicitly registered for the refresh rate.
11-14 09:28:55.607 D/InsetsController(26328): hide(ime())
11-14 09:29:05.916 D/InsetsController(26328): hide(ime())
11-14 09:29:08.616 D/InsetsController(26328): hide(ime())
11-14 09:30:06.303 D/InsetsController(26328): Setting requestedVisibleTypes to 498 (was 503)
11-14 09:30:06.348 D/InsetsController(26328): hide(ime())
11-14 09:30:06.353 D/InsetsController(26328): Setting requestedVisibleTypes to 496 (was 498)

Sent from my Pixel 7 Pro using Tapatalk

[lumping-sugar66]

I think I’m going to need the full logs. Please send crash.log and log.txt files

[nqk]

Originally Posted by lumping-sugar66

I think I’m going to need the full logs. Please send crash.log and log.txt files

Koreader just crashed and that msg popped up. No crash.log file was created. (I had deleted the existing crash.log file before I tried again). I don't know what log.txt file is and where to find it.

[nqk]

Yesterday I checked out MoonReader on Android and I found that it has a function called "Name Replacement". The idea is similar to this plugin, but it just replace the texts (regex supported) on the screen without modifying the epub file. Import and Export of the replacement rules is supported.

Would you support that? I hope without the need to modify the epub, it may work on my devices (Android and Pocketbook).

[lumping-sugar66]

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.

[lumping-sugar66]

HTML Replacer Plugin for KOReader - A Walkthrough (Part 2 - New Features: Footnotes & Shortcuts)

Second Functionality: Footnote Rules

This is a newly added feature - you're now able to add footnotes to the HTML with ease.

Starting fresh, instead of creating a replacement rule, I'm going to add a footnote rule. It looks like this:



It allows me to add:

• The pattern to match
• The footnote delimiter/indicator (the superscript marker you see)
• What you want the footnote text to be
• How frequently you want this footnote to appear

In my settings, I usually use 10,000 to 20,000 characters - this means the footnote gets introduced to patterns that match every few pages. Here I'm going to set it at 5,000 so that every 5,000 characters, an occurrence of "new terra" will get a footnote.

Otherwise, if you're adding this to a word that appears too frequently, you may end up polluting your book with the same footnote over and over again.

The description is what's visible in the menu. You don't need to set that, but it's helpful if you want to track rules - it'll default to the pattern if you don't specify one.



[HR][/HR]

Seeing Footnotes in Action

After adding the rule, I'm going to hit Reload with Replacements:



After the book loads, this is what it looks like:



Now it's important to note that the tags are introduced - a <sup> element is used for this - but it's not styled. It's up to you to style the HTML elements the way you want.

Here's the inserted HTML:



Here's how it looks with a custom footnote style applied:



And for me, it simply looks like this:



Now, as before, I need to go in and hit Apply Changes to Original before the changes are properly applied to my original file:



[HR][/HR]

Shortcuts

The plugin allows you to add replacement rules and footnote rules without going into the menu. You can easily just highlight a portion of the text:



Then select one of the options introduced with this plugin. You'll see Footnote Rule and Replacement Rule here. Press either of them and it will open the menu for adding a rule with pre-filled information:



You still need to go into the menu and hit Reload with Replacements before changes are applied properly to your book. But I find that I usually read a few pages, add all my rules, and then do a big batch of rule executions. Then I apply my EPUB that way.

So it's not as dynamic as Style Tweaks - this changes your EPUB completely - but it's still very useful if you want to add footnotes or simple replacements to your book as you go.

[HR][/HR]

Safety Net: Original Books are Always Backed Up

In any case where things have gone wrong, you'll always find your original books cached under this path:



These are unmodified original versions of the EPUB files that you can either manually grab, or as shown from the menu, you can just select Revert to Original.

[HR][/HR]


Summary

The HTML Replacer plugin gives you powerful control over your EPUB content:

• Use replacement rules to modify text or HTML elements with regex patterns
• Add contextual footnotes that appear at controlled intervals
• Preview changes before making them permanent
• Always have a backup to revert to if needed
• Use shortcuts to quickly add rules while reading

It's perfect for fixing formatting issues, adding contextual information, or customizing your reading experience.