Epub Format Construction Guide

Harrison Ainsworth

hxa7241+articles (ατ) googlemail (dοτ) com



A guide for making Epub ebooks/publications, sufficient for most purposes. It requires understanding of XHTML, CSS, XML. (1900 words)

Download an example publication – this document as Epub: http://www.hxa.name/articles/content/EpubGuide-hxa7241.epub



This is a guide for making IDPF Epub ebooks/publications. It is mostly an annotated example: this document itself in Epub form.

Not all details/variations are mentioned, but enough to obviate need of the specifications for normal use. And it is for making entirely conformant publications.

Included also is a description of optional extra styling for a particular reader (but still completely conformant).

You need an understanding of and ability to make XHTML/CSS and XML documents.


‘Epub’ is a standard from the International Digital Publishing Forum. It is an arrangement of several other standards (mainly: XHTML, CSS, XML, NCX, DCMI). There are three parts, addressing: content, package metadata, and archive (OPS, OPF, and OCF). It is powerful, straightforward, and non-proprietary.

Adobe Digital Editions

ADE’ is one of the first readers for Epub publications. It is very conformant with the standard. It can use an optional proprietary publication component: an extra stylesheet to adjust text-column appearance. (That is allowed by the standard.)

This guide was written using ADE version 1.0.467 .

1: XHTML Documents

Make the main content with XHTML, CSS, and images.

Relevant specifications: OPS, XHTML, CSS.


Use XHTML 1.1, but without the following modules:

  • Forms
  • Server-side Image Map
  • Intrinsic Events
  • Scripting

(XHTML 1.1 difference from XHTML 1 strict:

  • lang attribute not allowed (use xml:lang instead)
  • name attribute on a and map elements not allowed (use id instead)
  • ruby annotations are allowed)

Include XML declaration and XHTML doctype, at the top:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 

and xmlns attribute in html:

<html xmlns="http://www.w3.org/1999/xhtml">

Any unicode character, in UTF-8 or UTF-16, is allowed. But readers may have limited rendering capabilities.

(ADE 1.0 doesn't support: &shy; &ensp; &emsp; &thinsp; &zwnj; &zwj; &lrm; &rlm; &oline; &lceil; &rceil; &lfloor; &rfloor;)


A subset of CSS 2.1 is supported. A brief summary is awkward to make. For details, see the CSS part of the OPS specification.

Be simple, and use CSS 1 without the following properties:

  • background image related:
    • background-image
    • background-repeat
    • background-attachment
    • background-position
    • background
  • word-spacing
  • letter-spacing
  • text-transform
  • list-style-image

(There are also a few other minor details unsupported.) And don't use absolute positioning.

The CSS can be linked from the XHTML head, or put in style in head.

(ADE 1.0 doesn't support:

  • pseudo-classes/elements
  • text-align: justify;
  • font-variant: small-caps;
  • OPS extras:
    • display: oeb-page-head;
    • display: oeb-page-foot;
    • oeb-column-number: [integer];)


The XHTML can have images of the following types:

  • image/jpeg
  • image/png
  • image/gif
  • image/svg+xml


Use OpenType fonts. Reference them in the CSS with @font-face, eg.:

@font-face { font-family: "Minion Pro"; src: url(MinionPro.otf); }
@font-face { font-family: "Minion Pro"; font-style: italic;
   src: url(MinionPro-It.otf); }

Other descriptors allowed are: font-variant, font-weight, font-size.

2: Package And Container Files

Make these four files, according to the following descriptions:



It is ASCII, with no trailing end-of-line.

Specification: OCF


<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
      <rootfile full-path="content.opf"

If you rename or put the content.opf file elsewhere than in this guide, change the full-path attribute to match.

Specification: OCF


<?xml version="1.0"?>

<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="dcidid" 

   <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"
      <dc:title>Epub Format Construction Guide</dc:title>
      <dc:language xsi:type="dcterms:RFC3066">en</dc:language>
      <dc:identifier id="dcidid" opf:scheme="URI">
      <dc:subject>Non-fiction, technical article, tutorial, Epub, IDPF, ebook
      <dc:description>A guide for making Epub ebooks/publications, sufficient
         for most purposes. It requires understanding of XHTML, CSS, XML.
      <dc:creator>Harrison Ainsworth / HXA7241</dc:creator>
      <dc:publisher>Harrison Ainsworth / HXA7241</dc:publisher>
      <dc:date xsi:type="dcterms:W3CDTF">2007-12-28</dc:date>
      <dc:date xsi:type="dcterms:W3CDTF">2010-08-27</dc:date>
      <dc:rights>Creative Commons BY-SA 3.0 License.</dc:rights>

      <item id="ncx"      href="toc.ncx"                 
         media-type="application/x-dtbncx+xml" />
      <item id="css"      href="EpubGuide.css"           
         media-type="text/css" />
      <item id="logo"     href="hxa7241-logo.svg"         
         media-type="image/svg+xml" />
      <item id="title"    href="EpubGuide-title.html"    
         media-type="application/xhtml+xml" />
      <item id="contents" href="EpubGuide-contents.html" 
         media-type="application/xhtml+xml" />
      <item id="intro"    href="EpubGuide-intro.html"    
         media-type="application/xhtml+xml" />
      <item id="part1"    href="EpubGuide-1.html"        
         media-type="application/xhtml+xml" />
      <item id="part2"    href="EpubGuide-2.html"        
         media-type="application/xhtml+xml" />
      <item id="part3"    href="EpubGuide-3.html"        
         media-type="application/xhtml+xml" />
      <item id="part4"    href="EpubGuide-4.html"        
         media-type="application/xhtml+xml" />
      <item id="specs"    href="EpubGuide-specs.html"    
         media-type="application/xhtml+xml" />

   <spine toc="ncx">
      <itemref idref="title" />
      <itemref idref="contents" />
      <itemref idref="intro" />
      <itemref idref="part1" />
      <itemref idref="part2" />
      <itemref idref="part3" />
      <itemref idref="part4" />
      <itemref idref="specs" />

      <reference type="title-page" title="Title Page"        
         href="EpubGuide-title.html" />
      <reference type="toc"        title="Table of Contents" 
         href="EpubGuide-contents.html" />
      <reference type="text"       title="Text"              
         href="EpubGuide-intro.html" />


metadata (publication information)

Add publication information according to DCMI terms. Order is not significant, and duplicates are allowed.

Required terms:

  • title
  • language — use a RFC3066 language code
  • identifier — use a probably unique string: URI or ISBN would be good

Optional terms:

  • creator
  • contributor
  • publisher
  • subject
  • description
  • date
  • type
  • format
  • source
  • relation
  • coverage
  • rights

Some terms have optional attributes:

  • creator, contributor
  • date
    • opf:event — unstandardised: use something reasonable
  • identifier
    • opf:scheme — unstandardised: use something reasonable
  • date, format, identifier, language, type
    • xsi:type — use an appropriate standard term (such as W3CDTF for date)
  • contributor, coverage, creator, description, publisher, relation, rights, source, subject, title
    • xml:lang — use RFC-3066 format

manifest (document file list)

List every file that is part of the publication. But not: mimetype, container.xml, content.opf . The order is not significant.

Give correct mime-type in media-type attribute. ids are required and must be unique in the content.opf file.

spine (reading order definition)

List all XHTML documents in manifest (using the idref), and not anything else, and with no duplicates. The order is significant. (XHTML documents can be omitted, but then they must not be linked, referenced or reachable from any part of the publication.)

guide (main parts of document)

This section is optional.

Each item references a document file, and can have a fragment id. Allowed types are:

  • cover
  • title-page
  • toc (table of contents)
  • index
  • glossary
  • acknowledgements
  • bibliography
  • colophon
  • copyright-page
  • dedication
  • epigraph
  • foreword
  • loi (list of illustrations)
  • lot (list of tables)
  • notes
  • preface
  • text
  • other.[...]

Specifications: OPF, DCMI


<?xml version="1.0"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN" 

<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">

      <meta name="dtb:uid" content="http://www.hxa7241.org/articles/content/epup-guide_hxa7241_2007_2.epub"/>
      <meta name="dtb:depth" content="2"/>
      <meta name="dtb:totalPageCount" content="0"/>
      <meta name="dtb:maxPageNumber" content="0"/>

      <text>Epub Format Construction Guide</text>

      <navPoint id="navPoint-1" playOrder="1">
            <text>Title Page</text>
         <content src="EpubGuide-title.html"/>
      <navPoint id="navPoint-2" playOrder="2">
            <text>Table of Contents</text>
         <content src="EpubGuide-contents.html"/>
      <navPoint id="navPoint-3" playOrder="3">
         <content src="EpubGuide-intro.html"/>
      <navPoint id="navPoint-4" playOrder="4">
            <text>1: XHTML Documents</text>
         <content src="EpubGuide-1.html"/>
      <navPoint id="navPoint-5" playOrder="5">
            <text>2: Package And Container Files</text>
         <content src="EpubGuide-2.html"/>
         <navPoint id="navPoint-6" playOrder="6">
            <content src="EpubGuide-2.html#mimetype"/>
         <navPoint id="navPoint-7" playOrder="7">
            <content src="EpubGuide-2.html#containerxml"/>
         <navPoint id="navPoint-8" playOrder="8">
            <content src="EpubGuide-2.html#contentopf"/>
         <navPoint id="navPoint-9" playOrder="9">
            <content src="EpubGuide-2.html#tocncx"/>
      <navPoint id="navPoint-10" playOrder="10">
            <text>3: ADE stylesheet</text>
         <content src="EpubGuide-3.html"/>
      <navPoint id="navPoint-11" playOrder="11">
            <text>4: Container Structure</text>
         <content src="EpubGuide-4.html"/>
      <navPoint id="navPoint-12" playOrder="12">
            <text>Specifications List</text>
         <content src="EpubGuide-specs.html"/>



Set the following meta content attributes:

  • uid — to the unique identifier in content.opf
  • depth — to the depth of the contents tree (in navMap), integer, >= 1
  • totalPageCount — to 0
  • maxPageNumber — to 0


Make a table of contents, optionally hierarchical. (navMap doesn't need to include all XHTML files, since the content.opf spine does.)


Set both attributes:

  • id — to be unique in file
  • playOrder — to an integer, ordered in navMap, starting at 1

Set sub-parts:

  • the content of text in navLabel
  • the src attribute in content — to a URI of one of the XHTML files (fragment id allowed)

navPoints nested in navPoints are allowed.

(The Sony Reader, and perhaps others, have an extra restriction: fragment ids (in src attributes of contents.) are not allowed in top-level (non-nested) navPoints.)

Specification: NCX

3: ADE stylesheet

Optionally, make this file if you want extra control of column appearance with ADE 1.0:

  • page-template.xpgt

Add a link in the head of XHTML files to be styled:

<link rel="stylesheet" type="application/vnd.adobe-page-template+xml" 

Will the publication then be non-conformant? Non-standard files can be included (like fonts), but must have proper fallback handling. The standard implies that all fallback behaviour is explicitly standardised (in IDPF or component standards). For stylesheets, HTML rules say readers should ignore unrecognized types. And that would very likely happen. So it seems conformant, and safe.


<ade:template xmlns="http://www.w3.org/1999/xhtml" 

      <fo:simple-page-master master-name="single_column" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">

      <fo:simple-page-master master-name="single_column_head" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">
         <fo:region-before extent="8em"/>
         <fo:region-body margin-top="8em"/>

      <fo:simple-page-master master-name="two_column" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">
         <fo:region-body column-count="2" column-gap="3em"/>

      <fo:simple-page-master master-name="two_column_head" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">
         <fo:region-before extent="8em"/>
         <fo:region-body column-count="2" margin-top="8em" column-gap="3em"/>

      <fo:simple-page-master master-name="three_column" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">
         <fo:region-body column-count="3" column-gap="3em"/>

      <fo:simple-page-master master-name="three_column_head" margin-bottom="2em" 
         margin-top="2em" margin-left="2em" margin-right="2em">
         <fo:region-before extent="8em"/>
         <fo:region-body column-count="3" margin-top="8em" column-gap="3em"/>

               master-reference="three_column_head" page-position="first" 
               master-reference="three_column" ade:min-page-width="80em"/>
               master-reference="two_column_head" page-position="first" 
               master-reference="two_column" ade:min-page-width="50em"/>
               master-reference="single_column_head" page-position="first"/>

      <ade:styling-rule selector="#header" display="adobe-other-region" 


The selector attribute in ade:style/ade:styling-rule refers to a CSS selector. There is more detail at: http://blogs.adobe.com/digitaleditions/template.html

Specification: unknown

4: Container Structure

Arrange all files in the following directory structure:


(META-INF and its contents are special, but all other files can be arranged into any subdirectory structure. All references to them, in the various files, may have to be adjusted though.)

Then zip them into an archive with Zip. The filename extension should be ‘epub’, and the mimetype file must be first (and uncompressed), and extra file attributes must be excluded:

zip -X0 EpubGuide-hxa7241.epub mimetype
zip -Xur9D EpubGuide-hxa7241.epub *

(Get Zip from: ftp://ftp.info-zip.org/pub/infozip/ or http://www.info-zip.org/Zip.html .)

Other zip programs can probably be used, if they can do the same things.

(The Sony Reader, and perhaps others, have an extra requirement: each HTML file must be < 300KB and < 100KB when zipped.)

Specification: OCF

Specifications List

Open Publication Structure (OPS) 2.0 v1.0
Open Packaging Format (OPF) 2.0 v1.0
OEBPS Container Format (OCF) v1.0
ANSI/NISO Z39.86 - 2005 Specifications for the Digital Talking Book, NCX part (NCX)
DCMI Metadata Terms 2006-12-18 (DC)
CSS 2.1
XML 1.0



   title:`Epub Format Construction Guide`
   creator:`Harrison Ainsworth`


   description:`A guide for making Epub ebooks/publications, sufficient for most purposes. It requires understanding of XHTML, CSS, XML.`
   subject:`Epub, IDPF, ebook`

   type:`technical article`
   rights:`Creative Commons BY-SA 3.0 License`