kepubverto — EPUB to KEPUB for Kobo, without breaking the book

[Anak]

Anwer by Deepseek:

Rule 1 — Turn hyphenation ON everywhere

• * is the universal selector — it matches every element in the document (paragraphs, divs, spans, etc.).
  
• hyphens: auto tells the reading system to automatically break words at valid hyphenation points when a line is too short to fit the whole word. This is especially important for justified text (common in books), where without hyphenation you'd get large ugly gaps between words.
  
• -webkit-hyphens is the vendor-prefixed version needed by WebKit-based rendering engines. Many EPUB readers (Apple iBooks, Adobe Digital Editions, Kobo, older Android readers) use WebKit, so both lines are needed for maximum compatibility.

⚠️ Note: hyphens: auto only works correctly if the document declares a language, e.g. <html lang="en"> or <html xml:lang="en">. The reader needs to know which language's hyphenation dictionary to use.

Rule 2 — Turn hyphenation OFF for headings and table cells
This overrides the universal rule for a specific set of elements:

• h1–h6 — headings. A heading is usually short and on its own line; hyphenating it looks bad and can make it harder to scan. Many style guides forbid it.
  
• td — table cells. Cells are narrow and column-width-sensitive; hyphenation can break the visual alignment or cause ugly breaks inside short cell contents.
  
• !important ensures this rule wins even if another stylesheet later tries to re-enable hyphenation on these elements (EPUBs often stack multiple stylesheets: publisher defaults, user styles, etc.).

Strictly speaking, h1 already has higher specificity than *, so !important is somewhat defensive here — it's guarding against other rules with equal or higher specificity that might come later.

Why this pattern is common in EPUBs
EPUB renderers are essentially mini web browsers, so standard CSS applies. Hyphenation is one of the few typographic features that meaningfully improves readability on the small screens typical of e-readers and phones — but only for body prose. Applying it globally and then explicitly excluding headings and tables is a compact, robust way to get the best of both worlds:

Element Hyphenation Reason
Body text ✅ on Reduces ragged edges / word gaps in justified text
Headings ❌ off Short text, visual clarity
Table cells ❌ off Preserves column alignment and readability

Minor style notes
type="text/css" is deprecated in HTML5 and unnecessary in modern XHTML, but it's still widely used in EPUB 2 files for compatibility with older reading systems. EPUB 3 files can drop it.

Splitting the CSS across two <style> blocks is unnecessary — it could be a single block — but it's harmless and often results from how a tool generated the file.

[JSWolf]

Since my Kobo is not the best to test this due to config settings and patches, would hyphenation work in KePub if the code to turn it on was put in the CSS once instead of in each of the HTML files? If the answer is yes, I would prefer the code in CSS not in HTML.

[DNSB]

Originally Posted by JSWolf

I did check the code from kepubverto and looking at the hyphenation code, how does this code work to enable hyphens?

</style>
<style type="text/css">
* {
  -webkit-hyphens: auto;
  hyphens: auto;
}
h1, h2, h3, h4, h5, h6, td {
  -webkit-hyphens: none !important;
  hyphens: none !important;
}
</style>

Last time I looked, the first block with the * universal selector enables hyphenation for everything and then the second block with h1 ...h6, td disables hyphenation for the h1-h6 tags while the td disables hyphentation in a table cell.

You can add this into a CSS file instead of a style block in a XHTML files but check the positioning. Cascading style sheets are position sensitive hence the !importants.

[Kayadelenium]

Originally Posted by JSWolf

would hyphenation work in KePub if the code to turn it on was put in the CSS once instead of in each of the HTML files?

Yes. I tested it today on my Kobo with four copies of the same book (Pride and Prejudice from Project Gutenberg, whose own CSS says nothing about hyphenation):

• the rule in a style element in each chapter, as kepubverto writes it: hyphenated
• the same rule in one CSS file, linked at the end of each chapter's head: hyphenated
• the same file, linked at the start of the head, before the book's own CSS: hyphenated
• no rule at all: not hyphenated

So the Kobo reads the rule from a CSS file just as it does from a style element.

Why kepubverto still writes it into each chapter: a separate file means adding a file to the book, listing it in the OPF and linking it from every chapter. kepubverto does not touch the OPF, and the style element at the end of the head is always the last rule in the cascade, so the result does not depend on where the book's own stylesheets are linked. On the device the two give the same result. If you prefer the rule in the book's CSS, you can add it there yourself before converting and leave --hyphens off; kepubverto keeps your CSS as it is.

Originally Posted by DNSB

You can add this into a CSS file instead of a style block in a XHTML files but check the positioning.

Thanks, that is right, and it matches the test. For this book the position made no difference, because its CSS sets no hyphenation. It would matter against a rule of the book's with the same weight, such as its own * rule. A rule the book sets on an element, p { hyphens: manual } for example, wins over * wherever the file sits, which is why --hyphens auto leaves a publisher's own choice alone.

One correction to the explanation in #16: hyphenation on the Kobo does not need lang on the html element. On my Kobo, a Turkish book whose language was declared only in the OPF was hyphenated by Turkish rules.

Since my last post, kepubverto 0.3.0 is out. It adds --css, which puts your own CSS into every converted chapter, after kepubverto's rules. It refuses CSS that refers to a file, has @font-face, or would make epubveri report a problem in the book, and says why. The web page has the same option as an Extra CSS box: https://veripublica.github.io/kepubverto/

https://github.com/veripublica/kepub...ses/tag/v0.3.0
https://crates.io/crates/kepubverto
https://www.npmjs.com/package/@verip...epubverto-wasm

[JSWolf]

Can you make it an option to have the hyphenation code in the CSS or the HTML? I really dislike every HTML getting the same code when it can be done once in CSS.

I've not seem hyphens manual that I can recall. I have seen code to disable hyphenation. I don't see any reason not to add the hyphenation code to the CSS. But if it's an option, everybody will be happy.

[Kayadelenium]

kepubverto now has a calibre plugin. It converts the EPUBs in your calibre library and adds the KEPUB to each book beside its EPUB, which it leaves unchanged. It hands kepubverto the EPUB exactly as it is stored, so the book never goes through calibre's own conversion. It has its own thread in the Plugins forum, with the download: https://www.mobileread.com/forums/sh...d.php?t=375915

Questions about the plugin (installing, the menu, the report, the settings) belong there. Questions about the conversion itself, what kepubverto does to a book, stay here.

Originally Posted by JSWolf

Can you make it an option to have the hyphenation code in the CSS or the HTML?

Not yet. I have noted it, and here is where it stands.

Today, when hyphenation is turned on, kepubverto writes the rule into every chapter. It never changes the book's CSS files.

The calibre plugin does not change that. Its Hyphenation setting (as the book says, on, off) is the same as --hyphens: it decides whether the book is hyphenated, not where the rule goes. With "on", the rule is still written into every chapter.

Putting the rule in a CSS file instead means one of two things: changing one of the book's own CSS files, or adding a new CSS file to the book. Both need care. A book can have several CSS files, and different chapters can use different ones. I want to be sure the book stays valid before I offer it as an option, so I am not promising it yet.

Until then, you can already get what you want: add the rule to the book's CSS yourself, and convert with hyphenation left as the book says (no --hyphens). kepubverto keeps your CSS exactly as it is, and the test in #19 showed that the Kobo reads the rule from a CSS file.

https://github.com/veripublica/calib...ubverto-v0.1.0
https://github.com/veripublica/kepub...ses/tag/v0.3.0
https://crates.io/crates/kepubverto
https://www.npmjs.com/package/@verip...epubverto-wasm

[JSWolf]

delete post