iBooks renders epubs with empty pages

Karellen · 02-21-2026, 05:34 AM

I am wondering if iBooks requires some unique code in epubs to render them.

I've sideloaded a book series onto my iphone. Some of the epubs are rendered blank and I can only see the cover image. Other ebooks are perfectly fine. Out of 10 books, only 4 are rendered correctly.

CheckBook and EpubCheck are both clear. Both working and non-working epubs are structured and coded exactly the same. I can't see a single difference between them (obviously apart from the story text). There are no colours or backgrounds in the css to hide the text. I am at a loss as I can't figure out why they won't display.

Has anybody experienced this and know the cause?

I guess some will tell me to use another app, but that does not help as I would like to figure out where and why there is an error.

Doitsu · 02-21-2026, 07:40 AM

The problem might be caused by the stylesheets. If you remove them and side-load the books again, can you read them?
If so have the stylesheets validated by the W3C Stylesheet validator.

RbnJrg · 02-21-2026, 12:21 PM

Can you upload here one of your problematic epubs (of course, borkify the ebook before uploading it)? Of that way we can tell you better what is wrong.

Martinoptic · 02-21-2026, 12:33 PM

Epub2 or 3?
Any embedded fonts?

Karellen · 02-21-2026, 03:48 PM

Quote:

Originally Posted by Doitsu

The problem might be caused by the stylesheets. If you remove them and side-load the books again, can you read them?
If so have the stylesheets validated by the W3C Stylesheet validator.

Thank you for this. I have not come across that validator before.
It did reveal three errors. I had used text-decoration: normal instead of text-decoration: inherit.
Which then begs the question, why did three levels of checking not capture this?
1 - values are coloured blue in the stylesheet (in calibre) when unknown values are entered
2 - CheckBook did not flag it
3 - epubCheck did not flag it.

So I did correct those three errors. Sideloaded the epub again, but it still did not display.

Quote:

Originally Posted by RbnJrg

Can you upload here one of your problematic epubs (of course, borkify the ebook before uploading it)? Of that way we can tell you better what is wrong.

Sure. It is attached.

Quote:

Originally Posted by Martinoptic

Epub2 or 3?
Any embedded fonts?

epub v3
No embedded fonts.

KevinH · 02-21-2026, 04:37 PM

Took a peek and the structure of that epub is very strange:

For example: cover.xhtml is in OEBPS/Text/
but nav.xhtmnl, copyright.xhtml and p01c01.xhtml are all at the root of the epub

And your single image (cover.jpg) is stored in OEBPS/OEBPS/

Your content.opf is inside of OEBPS while you toc.ncx is at the root of the epub

And you stylesheet "stylesheet.css" is at OEBPS/

In addition your files have xml headers but no DOCTYPEs

As long as the links among the files are right, none of this should make a difference, although I have rarely seen an epub with this mixed up of a file structure.

So I used Sigil tools to
- move all of the .xhtml into OEBPS/Text/
- the .css files into OEBPS/Styles/
- the .jpg files into OEBPS/Images/

And I moved the .opf and .ncx into OEBPS/

Ran all pages through Sigil's Mend and then save it as a new epub.

This epub showed up just fine in Books.app (iBooks on my Mac). So I assume Books must have some rules unwritten rules about structure.

KevinH · 02-21-2026, 04:52 PM

What's funny is that I did a Checkpoint before allowing any change and then a diff after the Sigil Mend and the only thing that changed was the addition of a epub3 DOCTYPE
immediately after the xml header (which is a Sigil requirement but calibre discards them).

Code:

<!DOCTYPE html>

So nothing there should have impacted iBooks.

So the restructuring to Sigil Norm (ie. moving to a more normal epub structure) is what allowed iBooks to show the text for me on my Mac.

Interestingly, the epub3 spec specifically allows any structure (even yours) so this is a bug in iBooks not following the epub3 spec properly.

Hope this helps.

Falkor · 02-21-2026, 04:55 PM

In Calibre's editor, Tools > Arrange into folder will also do the trick.

KevinH · 02-21-2026, 05:05 PM

My best guess is relative hrefs for things stored above the opf are not being allowed (ie. hrefs in the opf that start with "../")

So maybe instead of moving everything into folders, just moving the content.opf to the root of the epub would work.

Ruling out hrefs in the opf that start with "../" is done primarily for security reasons (think of the location of the opf like an index.xhtml file and ereader as webserver that will not allow you to examine files outside that starting folder).

So for maximum use in e-reading devices, I would typically use a more normal structure for your files (ie. Calibre's Arrange into folder, or Sigil's "Restructure to Sigil Norm").

Doitsu · 02-21-2026, 05:16 PM

Quote:

Originally Posted by KevinH

Interestingly, the epub3 spec specifically allows any structure (even yours) so this is a bug in iBooks not following the epub3 spec properly.

The official Apple Books Asset Guide 5.3.1 doesn't explicitly mention any folder restrictions. Maybe they assume that every ebook has the same structure as the sample image?

KevinH · 02-21-2026, 05:45 PM

Quote:

Originally Posted by Doitsu

The official Apple Books Asset Guide 5.3.1 doesn't explicitly mention any folder restrictions. Maybe they assume that every ebook has the same structure as the sample image?

I just tested taking that same epub and only moving the content.opf out of the OEBPS folder up to root. Then saved it.

There are now no manifest hrefs that start with "../".

Now Books.app opened it and the text was readable just fine.

So I guess iBooks (Books) is allowing **almost** every structure as long as the opf manifest hrefs do not start with "../".

Probably a very good security move for unknown epubs by any e-reader. And important for developers/publishers of epubs to know.

Karellen · 02-21-2026, 06:08 PM

Quote:

Originally Posted by KevinH

Took a peek and the structure of that epub is very strange:

For example: cover.xhtml is in OEBPS/Text/
but nav.xhtmnl, copyright.xhtml and p01c01.xhtml are all at the root of the epub

And your single image (cover.jpg) is stored in OEBPS/OEBPS/

Your content.opf is inside of OEBPS while you toc.ncx is at the root of the epub

And you stylesheet "stylesheet.css" is at OEBPS/

In addition your files have xml headers but no DOCTYPEs

As long as the links among the files are right, none of this should make a difference, although I have rarely seen an epub with this mixed up of a file structure.

So I used Sigil tools to
- move all of the .xhtml into OEBPS/Text/
- the .css files into OEBPS/Styles/
- the .jpg files into OEBPS/Images/

And I moved the .opf and .ncx into OEBPS/

Ran all pages through Sigil's Mend and then save it as a new epub.

This epub showed up just fine in Books.app (iBooks on my Mac). So I assume Books must have some rules unwritten rules about structure.

Thank you @KevinH

I haven't really been overly concerned with the file structure. More often than not I leave it as it is and when adding new files, Calibre just tends do dump them in root, which might explain why it is a bit all over the place. I'll have to include the file sorting into my workflow more consistently from now on. I just assumed that as long as the internal links are correct, it should all work. Obviously not!

Looking at the 4 books that did display, I had run the Sort into folders tool as they were filed uniformly.

I tested your comments in two steps.
Added the DOCTYPE tag then sideloaded. The book did not display.
Removed the DOCTYPE tags, then sorted the file structure. After sideloading, the book displayed correctly.

So your comments regarding hrefs that start with "../" seems correct.

Thank you for your advice

02-21-2026, 05:34 AM	#1
Karellen Wizard Posts: 1,773 Karma: 9501034 Join Date: Sep 2021 Location: Australia Device: Kobo Libra 2	iBooks renders epubs with empty pages I am wondering if iBooks requires some unique code in epubs to render them. I've sideloaded a book series onto my iphone. Some of the epubs are rendered blank and I can only see the cover image. Other ebooks are perfectly fine. Out of 10 books, only 4 are rendered correctly. CheckBook and EpubCheck are both clear. Both working and non-working epubs are structured and coded exactly the same. I can't see a single difference between them (obviously apart from the story text). There are no colours or backgrounds in the css to hide the text. I am at a loss as I can't figure out why they won't display. Has anybody experienced this and know the cause? I guess some will tell me to use another app, but that does not help as I would like to figure out where and why there is an error.

02-21-2026, 07:40 AM	#2
Doitsu Grand Sorcerer Posts: 5,795 Karma: 24088595 Join Date: Dec 2010 Device: Kindle PW2	The problem might be caused by the stylesheets. If you remove them and side-load the books again, can you read them? If so have the stylesheets validated by the W3C Stylesheet validator. Last edited by Doitsu; 02-21-2026 at 08:12 AM.

02-21-2026, 04:37 PM	#6
KevinH Sigil Developer Posts: 9,409 Karma: 6733754 Join Date: Nov 2009 Device: many	Took a peek and the structure of that epub is very strange: For example: cover.xhtml is in OEBPS/Text/ but nav.xhtmnl, copyright.xhtml and p01c01.xhtml are all at the root of the epub And your single image (cover.jpg) is stored in OEBPS/OEBPS/ Your content.opf is inside of OEBPS while you toc.ncx is at the root of the epub And you stylesheet "stylesheet.css" is at OEBPS/ In addition your files have xml headers but no DOCTYPEs As long as the links among the files are right, none of this should make a difference, although I have rarely seen an epub with this mixed up of a file structure. So I used Sigil tools to - move all of the .xhtml into OEBPS/Text/ - the .css files into OEBPS/Styles/ - the .jpg files into OEBPS/Images/ And I moved the .opf and .ncx into OEBPS/ Ran all pages through Sigil's Mend and then save it as a new epub. This epub showed up just fine in Books.app (iBooks on my Mac). So I assume Books must have some rules unwritten rules about structure. Last edited by KevinH; 02-21-2026 at 04:55 PM.

02-21-2026, 04:52 PM	#7
KevinH Sigil Developer Posts: 9,409 Karma: 6733754 Join Date: Nov 2009 Device: many	What's funny is that I did a Checkpoint before allowing any change and then a diff after the Sigil Mend and the only thing that changed was the addition of a epub3 DOCTYPE immediately after the xml header (which is a Sigil requirement but calibre discards them). Code: <!DOCTYPE html> So nothing there should have impacted iBooks. So the restructuring to Sigil Norm (ie. moving to a more normal epub structure) is what allowed iBooks to show the text for me on my Mac. Interestingly, the epub3 spec specifically allows any structure (even yours) so this is a bug in iBooks not following the epub3 spec properly. Hope this helps.

02-21-2026, 05:05 PM	#9
KevinH Sigil Developer Posts: 9,409 Karma: 6733754 Join Date: Nov 2009 Device: many	My best guess is relative hrefs for things stored above the opf are not being allowed (ie. hrefs in the opf that start with "../") So maybe instead of moving everything into folders, just moving the content.opf to the root of the epub would work. Ruling out hrefs in the opf that start with "../" is done primarily for security reasons (think of the location of the opf like an index.xhtml file and ereader as webserver that will not allow you to examine files outside that starting folder). So for maximum use in e-reading devices, I would typically use a more normal structure for your files (ie. Calibre's Arrange into folder, or Sigil's "Restructure to Sigil Norm"). Last edited by KevinH; 02-21-2026 at 06:03 PM.

02-21-2026, 12:21 PM	#3
RbnJrg Wizard Posts: 1,913 Karma: 9553087 Join Date: Mar 2013 Location: Rosario - Santa Fe - Argentina Device: Kindle 4 NT	Can you upload here one of your problematic epubs (of course, borkify the ebook before uploading it)? Of that way we can tell you better what is wrong.

02-21-2026, 12:33 PM	#4
Martinoptic Bibliophist Posts: 8,142 Karma: 7319684 Join Date: Dec 2021 Location: England Device: none	Epub2 or 3? Any embedded fonts?

02-21-2026, 04:55 PM	#8
Falkor Zealot Posts: 108 Karma: 100000 Join Date: Dec 2024 Device: Tolino Shine 5	In Calibre's editor, Tools > Arrange into folder will also do the trick.

Thread Tools	Search this Thread
Show Printable Version Email this Page	Search this Thread: Advanced Search

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Blank pages (empty articles) in custom recipe	xiatian	Recipes	11	10-21-2018 03:22 AM
Empty Spans for iBooks compatibility	JSWolf	Workshop	24	12-19-2015 02:46 PM
All pages empty after converting epub in Calibre	Apostrophe	Conversion	1	01-29-2015 11:08 AM
InDesign to Epub (empty pages)	PauloCoe	EPUBReader	1	06-22-2011 09:56 AM
PDF Display- Hangup on empty pages	Manichean	Bookeen	6	10-15-2008 01:20 PM