23

I would like to create my own ePub documents from scratch without a tool so that I have full control over the final result.

What is the absolute minimum set of required files to have a valid ePub file? Or, to put it in programming terms, what would an ePub "Hello, world." file look like?

Improve this question
1

2 Answers 2

Reset to default
22

Here's an epub 3.0 file that validates with epubcheck 3.0.1 (the current version at the time of writing). There's plenty more info that can (and should) go in there, of course, but you asked for minimums. We'll start with file structure: in the root directory, there's one mimetype file and two folders--the OEBPS and the META-INF. Here's the mimetype file contents:

application/epub+zip

be sure not to have any return/line break characters in there. In the META-INF folder, there's one file, the container.xml:

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
  <rootfiles>
    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
  </rootfiles>
</container>

In the OEBPS folder, things get slightly more complex. First is the content.opf file:

<?xml version="1.0" encoding="UTF-8" ?>
<package xmlns="http://www.idpf.org/2007/opf" xmlns:dc="http://purl.org/dc/elements/1.1/" unique-identifier="db-id" version="3.0">

<metadata>
    <dc:title id="t1">Title</dc:title>
    <dc:identifier id="db-id">isbn</dc:identifier>
    <meta property="dcterms:modified">2014-03-27T09:14:09Z</meta>
    <dc:language>en</dc:language>
</metadata>

<manifest>
    <item id="toc" properties="nav" href="toc.xhtml" media-type="application/xhtml+xml" />
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
    <item id="template_css" href="template.css" media-type="text/css" />
    <item id="hello" href="1_hello.xhtml" media-type="application/xhtml+xml" />
</manifest>

<spine toc="ncx">
    <itemref idref="hello" />
</spine>

</package>

Then comes the toc.xhtml file:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
<head>
<title>toc.xhtml</title>
<link href="template.css" rel="stylesheet" type="text/css" />
</head>

<body>

    <nav id="toc" epub:type="toc">
        <h1 class="frontmatter">Table of Contents</h1>
        <ol class="contents">
               <li><a href="1_hello.xhtml">Hello</a></li>
        </ol>

    </nav>

</body>

</html>

And finally we have the content of the ebook itself, in this case 1_hello.xhtml:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
<head>
<title>1_hello.xhtml</title>
<link href="template.css" rel="stylesheet" type="text/css" />
</head>

<body>

    <h1>Hello World!</h1>

</body>
</html>

As a bonus, there's a toc.ncx file. This is not required to be valid, but it's required if you want the book to have a working Table of Contents on epub 2.0.1 devices (which is pretty much all of them):

<?xml version="1.0" encoding="UTF-8" ?>
<ncx version="2005-1" xml:lang="en" xmlns="http://www.daisy.org/z3986/2005/ncx/">

<head>
    <meta name="dtb:uid" content="isbn"/>
    <meta name="dtb:depth" content="1"/>
</head>

<docTitle>
    <text></text>
</docTitle>

<navMap>
    <navPoint id="hello" playOrder="1">
        <navLabel><text>cover</text></navLabel>
        <content src="1_hello.xhtml" />
    </navPoint>
</navMap>

</ncx>

And there's also the template.css in there, which is just a CSS stylesheet. In this case, it looks like this:

h1 {
  text-align: center;
}

And that's it! For more complex stuff, there are a number of free epub 3 samples available at https://code.google.com/p/epub-samples/.

Improve this answer
9
  • I respect the level of effort you put into your answer but you do realize it isn't a valid ePub and you should provide more detail in case someone copies to produce from.
    – DᴀʀᴛʜVᴀᴅᴇʀ
    Mar 28, 2014 at 1:09
  • Hmm; validates for me just fine. What errors are you seeing and what version of epubcheck are you using?
    – Tom
    Mar 28, 2014 at 1:11
  • 2
    ill provide an answer with clarity when I have some extra time.
    – DᴀʀᴛʜVᴀᴅᴇʀ
    Mar 28, 2014 at 1:27
  • 2
    Sounds great! That's one of the things the Stack Exchange sites are best for.
    – Tom
    Mar 28, 2014 at 1:59
  • 1
    @Gramps Do these retailers require derivations from resp. additions to the standard? In that case, I would not support your "should be valid across the board" claim. This thinking led us to divergent technology in HTML 4 and consorts. If they don't adhere to the standard, nobody should support them. End of story.
    – Raphael
    Mar 28, 2014 at 12:43
6

In regards to my comments about Tom's ePub not validating there is an error in his toc.xhtml on line 13 and should be coded as <li><a href="1_hello.xhtml">Hello</a></li> which will produce the error message from IDPF validator as:

enter image description here

In regards to the version 3.0 ePub I disagree and believe it should be noted that when an ePub is built as ePub 3.0 format ONLY it will not validate other than 3.0 in epubcheck. This can be achieved and tested in the terminal using epubcheck command line (which is a different question).

If the provided ePub is submitted and ran against epubcheck version 2.0 it will fail for the following:

  • value of attribute "version" is invalid; must be equal to "2.0"
  • attribute "property" not allowed here; expected attribute "content", "id", "name", "scheme" or "xml:lang"
  • element "meta" missing required attributes "content" and "name"
  • text not allowed here; expected the element end-tag
  • attribute "properties" not allowed here; expected attribute "fallback", "fallback-style", "href", "media-type", "required-modules" or "required-namespace"
  • element "nav" not allowed anywhere; expected element "address", "blockquote", "del", "div", "dl", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "ins", "noscript", "ns:svg", "ol", "p", "pre", "script", "table" or "ul" (with xmlns:ns="http://www.w3.org/2000/svg")
  • element "nav" not allowed anywhere; expected element "address", "blockquote", "del", "div", "dl", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "ins", "noscript", "ns:svg", "ol", "p", "pre", "script", "table" or "ul" (with xmlns:ns="http://www.w3.org/2000/svg")

That displayed my argument with the industry standard is that a version 2.0 ePub CAN be built to support and function with devices that run version 3.0 and it should be coded as such for quality and validation.

Also, if we are talking about what the structure of ePubs are. Using a OEBPS file structure was technically meant for ePub's in version 1. Since it really doesn't matter what the file structure is as long as the container.xml points and finds a true .opf file I petition and build my ePubs like so:

META-INF
-container.xml
xhtml
-toc.xhtml
-.xhtml files
css
-stylesheet.css
content.opf
toc.ncx
mimetype

I find it easier for maintenance and less annoying searching for a .opf or .ncx file in either OEBPS, OPS, OPF, etc. etc. file structures.

Also Im a big fan of commenting my code and since it will not change the performance I code my manifest as such:

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

    <!-- .xhtml -->
    <item id="toc" href="toc.xhtml" media-type="application/xhtml+xml" />
    <item id="hello" href="1_hello.xhtml" media-type="application/xhtml+xml" />

    <!-- .css -->
    <item id="css_file" href="stylesheet.css" media-type="text/css" />
</manifest>
Improve this answer
1
  • Thanks for catching that unclosed quote in the toc.xhtml; I've corrected the typo in my original answer and double-checked the file by copying and pasting; it validates just fine on the current version of epubcheck.
    – Tom
    Apr 1, 2014 at 17:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.