Where do you start an ePUB and what is the
<guide> section of the .OPF file?
Liz Castro has a great post at her blog Pigs, Gourds, and Wikis titled “Where should an ebook begin?” In the post, she looks are various readers and what they usually show as the first page of an eBook of John Grisham’s The Litigator. As she shows, both the Kindle and iBooks open to the first page of the first chapter of the book. The Nook, however, opens to the first page of the eBook itself, that is the cover, because it currently does not recognize the reference type
"start" in the
<guide> section of the .OPF file. In my own testing, it appears that Adobe Digital Editions (ADE) doesn’t support
<guide> section is in some ways the red-headed stepchild of the .OPF file. It is generally the last content in the .OPF, and isn’t as familiar to most ePUB producers as the other parts. To understand it, let’s take a quick look at what makes up the .OPF file.
The .OPF file begins with a declaration and package tag that looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<package version="2.0" unique-identifier="PrimaryID" xmlns="http://www.idpf.org/2007/opf">
This is followed by the
<metadata> section, which has Dublin Core defined fields of information about the ePUB, plus the
<meta name="price" content="USD XX.XX"/> and
<meta name="cover" content="my_cover_image"/> tags.
Next is the
<manifest>. This a list of each item that is considered part of the publication: a document, an image file, a style sheet, or other component. Each item is defined with the following attributes:
<manifest> is the
<spine> defines the reading order of all
"application/x-dtbook+xml" files. Each
itemref includes an
idref that matches the id given to the file in the manifest and a
linear= attribute, which determines whether the file will show up as the reader turns pages or if the file will only be accessed through a link. A typical item entry would look like this:
<itemref idref="toc" linear="yes"/>
Finally, we get to the
<guide>. According to the official IDPF specs for ePUB, “The guide element identifies fundamental structural components of the publication, to enable Reading Systems to provide convenient access to them.” So how does the
<guide> work? Essentially, it points to where particular pieces of the book can be found, allowing reading systems to go directly to that file or location.
The structural components of the books are listed in reference elements contained within the
<guide> element. These components could refer to the table of contents, list of illustrations, foreword, bibliography, and many other standard parts of the book. Reading Systems are not required to use the
<guide> element in any way.
The structural components of the book that can be included in the reference type are:
- cover the book cover(s), jacket information, etc.
- title-page page with possibly title, author, publisher, and other metadata
- toc table of contents
- loi list of illustrations
- lot list of tables
- text First “real” page of content (e.g. “Chapter 1”)
Other types may be used when none of the predefined types are applicable; their names must begin with the string other. The value for the type attribute is case-sensitive.
You’ll note here that the actual ePUB 2 spec calls for
text to be used instead of
start, as recommended by Amazon for Kindle. After some testing by Liz Castro, I can report that both will actually work on the Kindle and in iBooks. If you want to follow the ePUB spec properly, you may want to choose
text in your
So why use
<guide> items? One reason is that if you are running your ePUB through KindleGen or are using your ePUB HTML files for Kindlegen, including
reference type="toc", and
reference type="start" will create links for these items in your Kindle edition. As the Amazon Kindle Publishing Guidelines state:
The Kindle platform supports guide items for defining the cover, the table of contents (TOC), and the start reading location (“Go To Beginning”).
We do not recommend adding additional guide items to your OPF file beyond these, as they will be grayed out in the menu options and may cause customer confusion. Important: Please note that guide items, especially the TOC guide item, are not intended to replace the table of contents.
iBooks also supports both
text. If you want the reader to go directly to the first page on content in your book and bypass the frontmatter, it makes sense to include it in ePUBs uploaded to iBooks.
I have usually included only the three
<guide> elements recommended by Amazon since it doesn’t appear that anything besides these three items is accessed by any reading platform. In the OPF file, it looks like this:
In the ePUB 3.0 spec,
<guide> is deprecated. This means that it isn’t necessarily recommended for use, but it will still work. The ePUB 3.0 spec recommends using landmarks as part of the new nav page, and landmarks include pretty much everything in the guide and more.
Are you using the
<guide> section as part of the OPF in your ePUBs? Have you found any additional function for it on any of the reading platforms?