EPUB 3 Best Practices Making it Work Right Now

By Bill Kasdorf

When EPUB 3.0 was officially unveiled at the Frankfurt Book Fair in October, 2011, it was taken by many as the spec to end all specs.

At last, we could really get to work creating ebooks with all the things we’d always wished for — basic things like the sophisticated typography and layout we can do in print, and beyond-print features like video and interactivity — as well as some things we hadn’t thought to want, like global language support and rich metadata. Not to mention something we knew we should do but that was “too hard” before: real accessibility. Best of all, we could make just one file that would work the same everywhere…

The euphoria didn’t last long. Sure, EPUB 3 told us how to do all those things; but did they all actually work anywhere?

That was 18 months ago. Guess what? Progress happens.

Now there are lots of EPUB 3-based reading systems. Devices like Nook and Kobo. Systems like Apple iBooks and Google Play. Specialized platforms like CourseSmart and VitalSource, the two leading textbook platforms. Browser-based systems like Readium for Chrome. Many more.

But they don’t always implement everything, or implement things the same way. And because EPUB 3 is designed to be so accommodating, it can be a bit bewildering at first. This combination of almost unlimited flexibility and a rapidly evolving ecosystem can create a paralyzing deer-in-the-headlights reaction among publishers that prevents them from taking advantage of the new EPUB 3 ecosystem.

You’re Not In This Alone

Fortunately, as support for EPUB 3 has gained momentum, lots of resources have emerged. EPUBCheck tells you if your EPUB 3 file has coding mistakes. The free Readium plug-in for Chrome lets you view your EPUB 3 files; it has implemented all EPUB 3.0 features. The Readium software is open-source, which will make it easier for reading systems to implement EPUB 3; there will soon be an open-source Readium SDK as well. IDPF, the organization that governs EPUB, has provided a wealth of EPUB 3 samples so you can see how other publishers have done things, and is developing a Compliance Test Suite that will test how well reading systems implement each feature of EPUB 3. The BISG publishes an EPUB 3 Support Grid that monitors which features of EPUB 3 are currently supported by each reading system. And O’Reilly recently published (in cooperation with the IDPF) EPUB 3 Best Practices, a clear and comprehensive guide to the spec, with helpful advice on what to do and what not to do to ensure that your EPUBs work well. (This article is largely based on that book, to which I contributed.)

More Than a Website in a Box

Because EPUB is a single file format (.epub), and because it is fundamentally based on modern Web standards (HTML5, CSS3, and JavaScript), people often think of EPUB 3 as “just a website in a box” that can be viewed offline. Actually, it’s a whole collection of files — content documents, style sheets, fonts, images, media resources, scripts, metadata and more — that is literally zipped up (an .epub is a type of .zip file) for reliable single-file delivery. More importantly, it’s an organized collection of files, governed by a “package file” that documents what the EPUB contains (in the manifest), what a reading system needs to know about the EPUB and everything in it (in the metadata), a default reading order (the spine) and so forth.

Still, a publication starts with the content, and true to EPUB 3’s Web-based foundation, EPUB 3 content documents are almost always XHTML5 files. (XHTML is HTML using the rules of XML; more about that below.) They can also be SVG — a vector- and XML-based image format — but there are few SVG-based reading systems. As those come along, we’ll see SVG used for manga, comics, graphic novels and other image-based publications. But for now, the focus is on XHTML5.

Building on the Built-in Semantics of XHTML5

There are two essential things that differentiate HTML5 from its predecessors: It eliminates presentational markup, or formatting (that’s handled by your CSS, or cascading style sheet, instead) and it provides specific semantics for structural elements. Where XHTML 1.1 uses general purpose container elements like

(which you can characterize with @class attributes, but for which there is no standard structural vocabulary), HTML5 provides elements with specific semantic meanings:

s for the hierarchical structure of a document,

s for things like sidebars and footnotes that sit outside that linear structure, and so forth. What this means is that with HTML5, browsers and reading systems can be built to natively understand what these components are and handle them properly.

But for backwards compatibility and EPUB’s consistent use of XML, when you use HTML5 in an EPUB, it needs to follow XML rules. They aren’t difficult; it just means that:

you can’t omit end tags, as you can in HTML;
element and attribute names are case-sensitive and need to be lowercase;
you have to include the slash in empty tags like
, and use “&” for ampersands in text;
and you have to declare namespaces, which provide a way to specify a source of formal definitions of terms, along with prefixes that are then added to those terms to indicate that they are being used according to that specification.

Otherwise, the markup is HTML5. That’s what’s meant by “XHTML5.”

EPUB 3 takes the semantics a step further. While it is based on the semantics inherent in HTML5, it adds a new “Structural Semantics Vocabulary” and a new “epub:type” attribute that provide much more specific (and useful!) ways to characterize what the components are. For example, an

might be a sidebar or a footnote, and an might link to either. Now you can mark up a footnote reference in the text as and its corresponding footnote as

and get a pop-up footnote instead of plain text.

New, and Better, Navigation

Another big change in EPUB 3 is that the old NCX navigation format used by EPUB 2 (and still used by Mobi) has been replaced by a much easier-to-use format, the EPUB Navigation Document. This is an XHTML5 document that uses the HTML5