Where do you start an ePUB and what is the <guide> section of the .OPF file?

  • SumoMe

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 "start" either.

The <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: id, href, and media-type.

After the <manifest> is the <spine>. The <spine> defines the reading order of all media-type="application/xhtml+xml" or "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
  • index
  • back-of-book
  • style
  • index
  • glossary
  • acknowledgements
  • bibliography
  • colophon
  • copyright-page
  • dedication
  • epigraph
  • foreword
  • loi   list of illustrations
  • lot   list of tables
  • notes
  • preface
  • 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 <guide> section.

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="cover", 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 start and 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:

image of the &lt;guide&gt; section of an OPF file

The <guide> section of an OPF file.

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?

6 thoughts on “Where do you start an ePUB and what is the <guide> section of the .OPF file?

  1. Although iBooks doesn’t seem to actually use it at present, Apple’s upload validator requires fixed-layout books to include a starting location of the type “text” or “bodymatter” in the guide. Perhaps they’re planning to hook some functionality to that location in a future release.

Leave a Reply

Your email address will not be published. Required fields are marked *