[Bug]: Table of contents not working for some epub #697

New Issue

2026-04-24T23:34:48+02:00

adam commented

2026-04-24 23:34:48 +02:00

Originally created by @lwobniar on GitHub (Sep 12, 2023).

Issue: Table of Contents is not working for some epub files (It does not happen to all epub). I can provide epubs for testing.

Steps to reproduce

Read epub on web client or iOS app.
Open Table of Contents
Click on any bookmarks.

Expected behaviour

Jumps to the selected chapter/section

Actual behaviour

Nothing happens. It stays on the original viewing page.

Originally created by @lwobniar on GitHub (Sep 12, 2023). Issue: Table of Contents is not working for some epub files (It does not happen to all epub). I can provide epubs for testing. ### Steps to reproduce 1. Read epub on web client or iOS app. 2. Open Table of Contents 3. Click on any bookmarks. ### Expected behaviour - Jumps to the selected chapter/section ### Actual behaviour - Nothing happens. It stays on the original viewing page.

adam added the bug ereader labels 2026-04-24 23:34:48 +02:00

adam commented

2026-04-24 23:34:50 +02:00

@nichwall commented on GitHub (Sep 12, 2023):

I can take a look at the non-working epub files again unless advplyr wants to take them.

Does the ToC work in other software?
Have you tested if converting with calibre fixes the ToC like it did the font scaling?

@nichwall commented on GitHub (Sep 12, 2023): I can take a look at the non-working epub files again unless advplyr wants to take them. Does the ToC work in other software? Have you tested if converting with calibre fixes the ToC like it did the font scaling?

adam commented

2026-04-24 23:34:50 +02:00

@lwobniar commented on GitHub (Sep 13, 2023):

The ToC works in other software (Calibre on PC and Books on iOS).

I just converted with Calibre (don't know why I didn't do this before) and it fixes the ToC like it did for font scaling. I'll send both files to you on discord.

@lwobniar commented on GitHub (Sep 13, 2023): The ToC works in other software (Calibre on PC and Books on iOS). I just converted with Calibre (don't know why I didn't do this before) and it fixes the ToC like it did for font scaling. I'll send both files to you on discord.

adam commented

2026-04-24 23:34:51 +02:00

@scooterx3 commented on GitHub (Oct 1, 2023):

You say you converted with Calibre, but can you share any specific settings you used to get it to produce a working TOC? I'm not familiar with Calibre, but I have tried just importing a book that isn't working, "convert" it (without changing anything in particular b/c I'm not sure what to change), then uploading the resulting .epub, but to no avail.

So if there were some specific alterations you made with the Calibre converter, could you share them? I'd like to manually update the ones I have as a stop-gap for now.

@scooterx3 commented on GitHub (Oct 1, 2023): You say you converted with Calibre, but can you share any specific settings you used to get it to produce a working TOC? I'm not familiar with Calibre, but I have tried just importing a book that isn't working, "convert" it (without changing anything in particular b/c I'm not sure what to change), then uploading the resulting .epub, but to no avail. So if there were some specific alterations you made with the Calibre converter, could you share them? I'd like to manually update the ones I have as a stop-gap for now.

adam commented

2026-04-24 23:34:51 +02:00

@lwobniar commented on GitHub (Oct 1, 2023):

You say you converted with Calibre, but can you share any specific settings you used to get it to produce a working TOC? I'm not familiar with Calibre, but I have tried just importing a book that isn't working, "convert" it (without changing anything in particular b/c I'm not sure what to change), then uploading the resulting .epub, but to no avail.

So if there were some specific alterations you made with the Calibre converter, could you share them? I'd like to manually update the ones I have as a stop-gap for now.

I don't recall using any special settings. I just tested again using all the defaults settings to convert the book I have from epub to epub on calibre (version 6.27) and the ToC of the new epub is working properly on ABS.

@lwobniar commented on GitHub (Oct 1, 2023): > You say you converted with Calibre, but can you share any specific settings you used to get it to produce a working TOC? I'm not familiar with Calibre, but I have tried just importing a book that isn't working, "convert" it (without changing anything in particular b/c I'm not sure what to change), then uploading the resulting .epub, but to no avail. > > So if there were some specific alterations you made with the Calibre converter, could you share them? I'd like to manually update the ones I have as a stop-gap for now. I don't recall using any special settings. I just tested again using all the defaults settings to convert the book I have from epub to epub on calibre (version 6.27) and the ToC of the new epub is working properly on ABS.

adam commented

2026-04-24 23:34:51 +02:00

@nichwall commented on GitHub (Oct 1, 2023):

Yeah, every time I have converted a file using calibre, I just use the default settings to convert to epub (either for removing DRM from a file or just sanitizing the file like this).

@scooterx3 if you want to send me a broken file I can take a look at it to try and help narrow down what's happening. I haven't looked at your file yet @lwobniar but hopefully will have time today.

Either the email on my GH profile or a DM Discord works (nyxholas in the ABS server).

@nichwall commented on GitHub (Oct 1, 2023): Yeah, every time I have converted a file using calibre, I just use the default settings to convert to epub (either for removing DRM from a file or just sanitizing the file like this). @scooterx3 if you want to send me a broken file I can take a look at it to try and help narrow down what's happening. I haven't looked at your file yet @lwobniar but hopefully will have time today. Either the email on my GH profile or a DM Discord works (nyxholas in the ABS server).

adam commented

2026-04-24 23:34:52 +02:00

@nichwall commented on GitHub (Oct 4, 2023):

I have not been able to figure out the ToC issues yet. Two reference sites:
Basic documentation: https://docs.fileformat.com/ebook/ncx/
More in depth explanation of the TOC format: http://www.jedisaber.com/eBooks/Tutorial.shtml

Arbitrarily picking chapter 8, the original file is referenced like this in the TOC (changed spacing to be easier to compare):

<navPoint id="a8" playOrder="8">
  <navLabel>
    <text>Falsehood Cookies</text>
  </navLabel>
  <content src="text/9780063204171_FalsehoodCookies.xhtml#_idParaDest-3"/>
</navPoint>

In the converted file (by Calibre), the TOC for chapter 8 looks like this:

<navPoint id="u5Xdy8JPlG5RcIjUSXsTgtE" playOrder="7" class="chapter">
  <navLabel>
    <text>Falsehood Cookies</text>
  </navLabel>
  <content src="OEBPS/text/9780063204171_FalsehoodCookies.xhtml"/>
</navPoint>

The ToC links work correctly from the ToC, but not from the ABS ToC flyout menu (in web browser, haven't tested anywhere else). I think the real culprit is the navPoint tag, specifically from the above link: "According to the spec, the id can be anything you want, but it's easier to keep track of things if you use the same id you used for that file in the .OPF file. Also, some readers won't properly display the Table of Contents if the ID doesn't match."

I have been playing with changing the navPoint and content src tags, but haven't gotten it to work yet.
The chapter files are pretty much identical, along with the .opf file.

(for future reference when I forget the commands to reconstruct an epub again)

cd [epub_directory]
zip -X0 modified.epub mimetype
zip -X9Dr modified.epub META-INF OEBPS

@nichwall commented on GitHub (Oct 4, 2023): I have not been able to figure out the ToC issues yet. Two reference sites: Basic documentation: https://docs.fileformat.com/ebook/ncx/ More in depth explanation of the TOC format: http://www.jedisaber.com/eBooks/Tutorial.shtml Arbitrarily picking chapter 8, the original file is referenced like this in the TOC (changed spacing to be easier to compare): ``` <navPoint id="a8" playOrder="8"> <navLabel> <text>Falsehood Cookies</text> </navLabel> <content src="text/9780063204171_FalsehoodCookies.xhtml#_idParaDest-3"/> </navPoint> ``` In the converted file (by Calibre), the TOC for chapter 8 looks like this: ``` <navPoint id="u5Xdy8JPlG5RcIjUSXsTgtE" playOrder="7" class="chapter"> <navLabel> <text>Falsehood Cookies</text> </navLabel> <content src="OEBPS/text/9780063204171_FalsehoodCookies.xhtml"/> </navPoint> ``` The ToC links work correctly from the ToC, but not from the ABS ToC flyout menu (in web browser, haven't tested anywhere else). I think the real culprit is the `navPoint` tag, specifically from the above link: "_According to the spec, the id can be anything you want, but it's easier to keep track of things if you use the same id you used for that file in the .OPF file. Also, some readers won't properly display the Table of Contents if the ID doesn't match._" I have been playing with changing the `navPoint` and `content src` tags, but haven't gotten it to work yet. The chapter files are pretty much identical, along with the `.opf` file. <details> <summary> (for future reference when I forget the commands to reconstruct an epub again) </summary> ``` cd [epub_directory] zip -X0 modified.epub mimetype zip -X9Dr modified.epub META-INF OEBPS ``` </details>

adam commented

2026-04-24 23:34:52 +02:00

@KaiStarkk commented on GitHub (Oct 26, 2024):

Worth noting here that ustream epubjs has table of contents, per their demo. Might be worth considering as workaround for issues with the embedded ToC links: https://github.com/futurepress/epubjs-reader/blob/master/src/controllers/toc_controller.js

@KaiStarkk commented on GitHub (Oct 26, 2024): Worth noting here that ustream epubjs has table of contents, per their demo. Might be worth considering as workaround for issues with the embedded ToC links: https://github.com/futurepress/epubjs-reader/blob/master/src/controllers/toc_controller.js

adam commented

2026-04-24 23:34:53 +02:00

@advplyr commented on GitHub (Oct 26, 2024):

I believe there has been fixes to the TOC on the web client since this was opened. I haven't done testing but it would be worth checking if this isn't already figured out on the web client and if so it can be put in the mobile app. The ereader code is largely the same.

@advplyr commented on GitHub (Oct 26, 2024): I believe there has been fixes to the TOC on the web client since this was opened. I haven't done testing but it would be worth checking if this isn't already figured out on the web client and if so it can be put in the mobile app. The ereader code is largely the same.

adam commented

2026-04-24 23:34:54 +02:00

@gordho commented on GitHub (Nov 7, 2024):

I have at least one book where TOC works in the web client but not in the iOS app.

@gordho commented on GitHub (Nov 7, 2024): I have at least one book where TOC works in the web client but not in the iOS app.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/audiobookshelf-app#697