An ePub Tutorial‎ > ‎

Adding Content


This section covers adding the HTML files and the basics of XHTML/CSS compliancy needed so that ePub readers can display your stuff.

I won’t be covering file format conversion or HTML massage here (and the file over at the University of Pennsylvania needs it).

Content Files

HTML Files

Velveteen Rabbit - Content Tree

EPub readers often have a difficult time dealing with an Epub file that contains all the HTML in one file.  As a result, you should break your HTML into smaller chunks (one per chapter usually works well).

Your HTML files need to stick to the XHTML 1.1 specification and the CSS 2.1 specification, with a few limitations.  Most commonly, you'll need the beginning of your HTML to look like this:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="">

Ainsworth’s guide has the nitty-gritty.

Epubcheck later on can help you find trouble spots after you compile the ePub, but HTML Tidy can work directly on the HTML files themselves.  If you're working from a Mac OS X computer, you already have tidy installed.

CSS Stylesheets

You can also include separate CSS files (useful since an ePub file often has multiple HTML documents).  Stylesheets need to stick to the CSS 2.1 specification.

You include a stylesheet using the following code (which has to be part of the <head> element):

<html xmlns="">
    <title>Title of Your Page</title>
    <link rel="stylesheet" type="text/css" href="relative/path/to/file" />

Font Files

OpenType font files can be included and referenced in the usual CSS manner.


Images typically supported by browsers can be included.  This includes PNG, GIF, and JPG; SVG can also be included, but not every ePub reader (or format you can derive from the ePub file) can deal with such images.

Updating metadata.opf

You need to update two sections in metadata.opf:


The list of content files, as well as the toc.ncx we created earlier). This includes the CSS files, fonts, and images (but not metadata.opf, container.xml, or mimetype).

<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>

<item id="titlepage" href="content/title.html" media-type="application/xhtml+xml"/>
<item id="dedication" href="content/dedication.html" media-type="application/xhtml+xml"/>
<item id="listillustrations" href="content/list-illustrations.html" media-type="application/xhtml+xml"/>
<item id="text" href="content/text.html" media-type="application/xhtml+xml"/>
<item id="credits" href="content/credits.html" media-type="application/xhtml+xml"/>

<item id="image_1" href="content/images/christmas-morning.jpg" media-type="image/jpeg"/>
<item id="image_2" href="content/images/anxious-times.jpg" media-type="image/jpeg"/>
<item id="image_3" href="content/images/at-last.jpg" media-type="image/jpeg"/>
<item id="image_4" href="content/images/fairy-flower.jpg" media-type="image/jpeg"/>
<item id="image_5" href="content/images/skin-horse.jpg" media-type="image/jpeg"/>
<item id="image_6" href="content/images/spring-time.jpg" media-type="image/jpeg"/>
<item id="image_7" href="content/images/summer-days.jpg" media-type="image/jpeg"/>
<item id="image_8" href="content/images/capital-t.jpg" media-type="image/jpeg"/>

You need to include, for each item: an id (which can be used to refer to it later in the file), path to the file, and the media type of the file. Here’s a list of all the media types.


Reading order of the HTML files from the manifest. You don’t want to include images, CSS, or fonts here.

    <spine toc="ncx">
<itemref idref="titlepage"/>
<itemref idref="dedication"/>
<itemref idref="listillustrations"/>
<itemref idref="text"/>
<itemref idref="credits"/>

The idref attribute refers back to the item’s id in the manifest.

Media Types Quick Examples

<item id="titlepage" href="content/title.html" media-type="application/xhtml+xml"/>
<item id="stylesheet" href="content/stylesheet.css" media-type="text/css"/>
JPG Image
<item id="image_1" href="content/images/christmas-morning.jpg" media-type="image/jpeg"/>

Updating toc.ncx

This is the table of contents, listing each navigation point (chapters and such) under the navigation map.

<navPoint id="navpoint-1" playOrder="1">
<text>Title Page</text>
<content src="content/title.html"/>
<navPoint id="navpoint-2" playOrder="2">
<content src="content/dedication.html"/>
<navPoint id="navpoint-3" playOrder="3">
<text>List of Illustrations</text>
<content src="content/list-illustrations.html"/>
<navPoint id="navpoint-4" playOrder="4">
<text>Start Reading</text>
<content src="content/text.html"/>
<navPoint id="navpoint-5" playOrder="5">
<content src="content/credits.html"/>

Every navigation point (navPoint) has a unique navigation point id and a play order, with the label of that oint and the content source specified.

    <navPoint id="navpoint-5" playOrder="5">
<content src="content/credits.html"/>