An EPUB is a ZIP archive containing your text as XHTML, a package document listing everything, and a navigation document. You can build one by hand, but the container has strict rules that ordinary zip tools break, which is why most people export one from software instead.
Knowing what is inside is still worth it, because it is what error messages refer to when a file fails validation.
What Is Inside
mimetype
META-INF/
container.xml
OEBPS/
content.opf the package document
nav.xhtml the navigation document
chapter-01.xhtml content documents
stylesheet.css
images/Folder names other than META-INF are conventions rather than requirements.
mimetype contains the single string application/epub+zip and nothing else. It is the file that most hand-built EPUBs get wrong. See below.
META-INF/container.xml tells a reading system where to find the package document. Its full-path is relative to the root of the container, not to the META-INF folder, which is a common error.
The package document, usually content.opf, is the book's inventory. It has three parts in a fixed order: metadata, then manifest, then spine. The manifest lists every resource; the spine gives the reading order.
The navigation document carries the table of contents. Exactly one manifest item must be flagged with the nav property, and the document must contain a toc nav element. This is required in every EPUB, including novels.
Content documents hold the text, one file per chapter by convention.
The Rules That Break Files
The mimetype rules. The specification places five separate MUST requirements on one nineteen-byte file: it must be the first file in the archive, contain exactly application/epub+zip in US-ASCII, carry no leading or trailing whitespace, not begin with a byte order mark, not be compressed or encrypted, and carry no extra field in its ZIP header.
Ordinary archive tools violate at least one of these, usually by compressing it or reordering entries. This is why you cannot select a folder, choose "compress", and rename the result to .epub.
Everything else in the container may be compressed normally. The belief that an EPUB must be uncompressed throughout is wrong.
Content must be XHTML, not HTML. The spec requires content documents to conform "to the XML syntax". Void elements must be closed, ampersands escaped, tags properly nested. Markup that a browser silently forgives will fail validation here, and this is the single largest source of errors.
Everything must be in the manifest. The manifest "MUST list all publication resources". A stylesheet or image that exists but is not listed is an error, and one listed but absent is a different error.
Paths are case sensitive. Chapter1.xhtml and chapter1.xhtml are different files, even if your operating system disagrees. This is why files work locally and fail validation.
Building One
By export, which is what almost everyone should do. Writing software produces the container correctly, including the mimetype rules.
By hand, if you want to understand it or need precise control. Assemble the structure above, then zip in two passes: add mimetype first with compression disabled, then add everything else. Command-line zip tools support this; graphical ones generally do not.
Then validate. EPUBCheck is the reference validator, and retailers use it as a gate. Do not skip this: reading systems are forgiving and will happily display a file that breaks the rules a store will reject. See common EPUB validation errors.
Exporting From Deckle
Deckle builds the container directly rather than zipping a folder, so the mimetype rules are satisfied by construction: it is written first and stored uncompressed.
The output is reflowable, which is correct for a novel. Deckle writes the package document with the four required metadata items, generates the navigation document, and produces one content document per chapter.
Two things worth knowing. The navigation document is only written when the Include table of contents option is on, and that document is required by the specification and by every major retailer, so leave it on for EPUB export even if you do not want a visible contents page in a print edition. And any image that could not be embedded is reported in the export warnings, naming the document it came from, which is worth reading before you upload.
Common Mistakes
- Zipping a folder and renaming it. The mimetype has five requirements ordinary tools break.
- Writing HTML rather than XHTML. Unclosed tags and raw ampersands are the top cause of errors.
- Pointing
full-pathat META-INF. It is relative to the container root. - Leaving resources out of the manifest. Every file must be listed.
- Ignoring filename case. EPUB paths are case sensitive.
- Skipping validation because it opens in your reader. Readers forgive; retailers do not.
FAQ
Q: Can I just rename a ZIP to .epub? A: No. The mimetype file must be first and uncompressed, which normal zip tools do not do.
Q: Do I need a toc.ncx? A: No. That is an EPUB 2 legacy file. Only the navigation document is required.
Q: How many content documents should I have? A: One per chapter is conventional. It keeps files small and makes navigation straightforward.
Q: Does the folder have to be called OEBPS?
A: No. Only META-INF and mimetype are fixed; the rest is convention.
Q: What validates an EPUB? A: EPUBCheck, maintained by the W3C. Many tools embed it, and Amazon's Kindle Previewer runs its own checks.