KFX to EPUB conversion can break page-list, while KFX Input plugin works consistently

[mallomar]

When converting KFX files containing page number information to EPUB using Calibre's standard conversion engine (the "Convert books" button), the resulting page-list in the nav.xhtml can sometimes be broken or have its href attributes stripped. While this doesn't seem to happen with every single KFX file, I have found it to be a frequent issue. When it occurs, it makes the reference page numbers unusable in compliant e-reader software like KOReader and causes the EPUB to fail epubcheck with pathing errors (RSC-007).

This issue does not appear to happen when converting the same KFX files using the KFX Input plugin's dedicated conversion feature, which has been consistently successful.

Steps to Reproduce:

1. Start with a KFX-format book that is known to contain a page map where this issue can be reproduced.
2. Convert the book to EPUB using Calibre's standard "Convert books" feature.
3. Inspect the output EPUB. The <nav epub:type="page-list"> section within nav.xhtml may have incorrect or missing href attributes for its list items. For example, <a>1</a> instead of <a href="OEBPS/file.xhtml#page_1">1</a>.
4. Now, take the same original KFX file and convert it again, but this time use the KFX Input plugin's conversion method (e.g., right-click the book -> KFX Input -> Convert to EPUB).
5. Inspect this second EPUB. Its page-list is generated correctly with complete and valid href attributes.

There appears to be a discrepancy in how Calibre's main conversion engine and the KFX Input plugin handle the page map data from some KFX source files. The standard engine can fail to correctly reconstruct the page-list navigation, leading to a broken EPUB. The plugin's method, however, seems to produce a correctly structured and functional EPUB more reliably.

I can provide scrambled versions of the EPUBs generated by both Calibre's standard converter and the KFX Input plugin for a direct comparison if that would be helpful for debugging.

My System Details:

• Calibre Version: [8.16]
• Operating System: [macOS Sequoia 15.6]

(I am posting this here because I was unable to use the official bug tracker. This is the second time I've tried to report this bug on Launchpad over the last few weeks, and I receive an "Oops!" error page each time I try to log in.)

[BetterRed]

Latest calibre version is 8.6 ==>> https://calibre-ebook.com/whats-new

BR

[DNSB]

Originally Posted by mallomar

My System Details:

• Calibre Version: [8.16]
• Operating System: [macOS Sequoia 15.6]

(I am posting this here because I was unable to use the official bug tracker. This is the second time I've tried to report this bug on Launchpad over the last few weeks, and I receive an "Oops!" error page each time I try to log in.)

Is the calibre version a typo? It is 10 major versions ahead of the current calibre 8.6 release.

And the MacOS Sequoia version would appear to be a beta.

As for the difference between using the calibre conversion pipeline and the KFX Input plugin? What you are running into is the same reason I use the KindleUnpack plugin for azw3/KF8. The output ePub generated by KindleUnpack is a lot closer to the original ePub input to KDP than is the output from the calibre conversion pipeline. OTOH, the calibre conversion can handle a lot more formats. That it can munge the structure, CSS, etc. of an output ePub from the semicompiled KFX or azw3/KF8 input is something that you may have to live with if you are going to insist on using calibre's conversion pipeline.

I suspect that you are not going to see any major changes in the calibre conversion pipeline since that would be time intensive with testing required on multiple formats both input and output.

[kovidgoyal]

KFX isnt a supported format in calibre, except via the third party KFX Input plugin. You should report the issue in that plugin's thread.

[jhowell]

Originally Posted by mallomar

I can provide scrambled versions of the EPUBs generated by both Calibre's standard converter and the KFX Input plugin for a direct comparison if that would be helpful for debugging.

I am willing to look into it if you provide the files that exhibit the problem.

[mallomar]

Originally Posted by BetterRed

Latest calibre version is 8.6 ==>> https://calibre-ebook.com/whats-new

BR

Thanks, I mistyped, it's Calibre 8.6

Originally Posted by DNSB

Is the calibre version a typo? It is 10 major versions ahead of the current calibre 8.6 release.

And the MacOS Sequoia version would appear to be a beta.

Yes, a typo and yup, you're correct, it's a beta, though I don't imagine that's having an impact here.

Originally Posted by DNSB

As for the difference between using the calibre conversion pipeline and the KFX Input plugin? What you are running into is the same reason I use the KindleUnpack plugin for azw3/KF8. The output ePub generated by KindleUnpack is a lot closer to the original ePub input to KDP than is the output from the calibre conversion pipeline. OTOH, the calibre conversion can handle a lot more formats. That it can munge the structure, CSS, etc. of an output ePub from the semicompiled KFX or azw3/KF8 input is something that you may have to live with if you are going to insist on using calibre's conversion pipeline.

I suspect that you are not going to see any major changes in the calibre conversion pipeline since that would be time intensive with testing required on multiple formats both input and output.

Thank you, I've been using boh KFX Input's KFX to EPUB and Kindle Unpack's KF8 to EPUB because of these same reasons, but I figured these two plugins handling it better than Calibre must be a bug in Calibre. I've been using Calibre for over a decade (since 2014) but I am not a developer and do not deem to understand all of its many intricacies.

Originally Posted by kovidgoyal

KFX isnt a supported format in calibre, except via the third party KFX Input plugin. You should report the issue in that plugin's thread.

Thanks, I thought KFX showing up in Calibre's conversion menu meant it's being handled by Calibre, but I guess not? What is handling the conversion if it's not Calibre and KFX Input's convert to EPUB gives different results?

Originally Posted by jhowell

I am willing to look into it if you provide the files that exhibit the problem.

Sure, we discussed one book here. I am attaching the scrambled EPUB from Calibre's conversion engine and from KFX Input's Convert to EPUB. I have also noticed the problem recently in two other books – Big Swiss and Chain Gang All Stars. I am attaching the scrambled KFX Input and Calibre Engine conversions for those as well.