Example - EPUB 3 Best Practices

This page provides specific information regarding the EPUB variant used in "EPUB 3 Best Practices".


The EPUB variant used by this book largely matches that described in EPUB 3 Best Practices, but there are some exceptions.

Because this is an EPUB 3.0 document, it has both a NAV file (newly defined in EPUB 3) and an NCX file (required for backward compatibility with EPUB 2). Both the Nav file (bk01-toc.html) and the navmap hierarchy in the NCX file (toc.ncx) cover the Chapter and Section levels.


O'Reilly produces a large number of high-quality technical reference works for software developers. Let's examine their EPUB archive for EPUB 3 Best Practices.

Directory Tree

The file tree contains about 100 files, a third of which (e.g., fonts, HTML) reside in the OEBPS directory (tsk). The document contains both *.png and *.png.jpg images; wazzup? Most (but not all) of the images reside in the OEBPS/images directory; the exceptions appear to be used by all O'Reilly books.

| META-INF/                # EPUB metadata
| | container.xml          # media type, paths (XML)
| mimetype                 # "application/epub+zip"
| OEBPS/                   # Open eBook Publication Structure
| | author_bios.html       # author's biographies (HTML)
| | bk01-toc.html          # Table of Contents (HTML)
| | ch??.html              # chapter pages (HTML)
| | co02.html              # colophon page (HTML)
| | content.opf            # Open Packaging Format (XML)
| | copyright.html         # copyright page (HTML)
| | core.css               # Cascading Style Sheets (CSS)
| | cover.xhtml            # cover page (HTML)
| | images/                # raster image files
| | | *.png                # PNG files (44)
| | | *.png.jpg            # JPEG versions of PNG files? (17)
| | index.html             # index header page (HTML)
| | ix01.html              # index content page (HTML)
| | oreilly_large.png.jpg  # image of O'Reilly Logotype
| | orm_front_cover.jpg    # image of book's front cover
| | pr??.html              # preface pages (HTML)
| | toc.ncx                # table of contents (XML)

Package Document

Per META-INF/container.xml, OEBPS/content.opf is our package document. This is a substantial file (167 lines), so here's another summary:

package       # prefix, unique-identifier, version, xmlns
| metadata    # xmlns:dc, xmlns:opf
| | dc:*      # creator, identifier, language, ...
| | meta      # name="cover" content="cover-image" ?
| | meta      # content="cover-image" name="cover" ?
| manifest    # list of files included in document
| | item      # id, href, media-type
| | ...
| spine       # toc="ncx"
| | itemref   # idref=cover
| | itemref   # idref=id-id652686
| | ...
| guide
| | reference # href, title, type


The spine entry lists the enclosed content files, in the "normal" reading order. The toc attribute's value (ncx) tells us to look for toc.ncx, a file which contains EPUB 2 navigation hints and other metadata.


The guide entry lists only three references:

  • The cover page is "cover.html".
  • The toc page ("Table of Contents") is "bk01-toc.html".
  • The index page is "index.html".

The OEBPS/content.opf file contains two indications that bk01-toc.html is the Nav file. I'm not yet sure which of these is definitive, reliable, etc:

  • the guide entry for type toc
  • the manifest entry for item htmltoc

Looking inside bk01-toc.html, we can tell that it is actually an XHTML file, which guarantees some useful syntactic decorum (e.g., closing tags).

NCX file

The NCX Navigation Center eXtended file (toc.ncx) is included, as required for backward compatibility with EPUB 2.

EPUB 3 Best Practices
| The Future
| ...
1. Package Document and Metadata
| Vocabularies
| ...

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r17 - 28 Oct 2016, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email