EPUB Format: Internal Structure, Creation and Conversion

EPUB Format: Internal Structure, Creation and Conversion

EPUB (Electronic Publication) is the open standard format for ebooks, maintained by the W3C. It's supported by most readers: Kindle (via conversion), Kobo, Apple Books, Adobe Digital Editions, and any app with EPUB support.

Internal Structure of an EPUB

An EPUB file is essentially a renamed ZIP archive. Extracting it reveals:

book.epub (= ZIP)
├── mimetype                    ← must be the first file, uncompressed
├── META-INF/
│   └── container.xml           ← points to the main OPF file
└── OEBPS/
    ├── content.opf             ← manifest: metadata + file list
    ├── nav.xhtml               ← table of contents (EPUB 3)
    ├── toc.ncx                 ← table of contents (EPUB 2, backwards compatibility)
    ├── chapter01.xhtml
    ├── chapter02.xhtml
    ├── styles/style.css
    └── images/cover.jpg

The mimetype file

Must contain exactly (no trailing newline):

application/epub+zip

META-INF/container.xml

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

OEBPS/content.opf — The Manifest

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier id="uid">978-0-000-00000-0</dc:identifier>
    <dc:title>My Example Ebook</dc:title>
    <dc:creator>Author Name</dc:creator>
    <dc:language>en</dc:language>
    <meta property="dcterms:modified">2024-01-15T00:00:00Z</meta>
  </metadata>

  <manifest>
    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
    <item id="ch01" href="chapter01.xhtml" media-type="application/xhtml+xml"/>
    <item id="ch02" href="chapter02.xhtml" media-type="application/xhtml+xml"/>
    <item id="css"  href="styles/style.css" media-type="text/css"/>
    <item id="cover" href="images/cover.jpg" media-type="image/jpeg" properties="cover-image"/>
  </manifest>

  <spine>
    <itemref idref="nav"/>
    <itemref idref="ch01"/>
    <itemref idref="ch02"/>
  </spine>
</package>

EPUB 3 Table of Contents (nav.xhtml)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops">
<head><title>Contents</title></head>
<body>
  <nav epub:type="toc">
    <h1>Table of Contents</h1>
    <ol>
      <li><a href="chapter01.xhtml">Chapter 1: Introduction</a></li>
      <li><a href="chapter02.xhtml">Chapter 2: Development</a></li>
    </ol>
  </nav>
</body>
</html>

Creating EPUB from Markdown with Pandoc

Pandoc is the most comprehensive command-line tool for generating EPUB:

# Basic EPUB from a Markdown file
pandoc input.md -o book.epub

# With metadata and cover
pandoc input.md \
  --metadata title="My Book" \
  --metadata author="Your Name" \
  --metadata lang="en" \
  --epub-cover-image=cover.jpg \
  --css=styles/epub.css \
  -o book.epub

# From multiple chapters
pandoc chapter01.md chapter02.md chapter03.md \
  --metadata title="Complete Novel" \
  --toc --toc-depth=2 \
  -o novel.epub

# With separate metadata file (metadata.yaml)
pandoc input.md --metadata-file=metadata.yaml -o book.epub

Sample metadata.yaml:

---
title: 'The Book Title'
author:
  - 'Main Author'
  - 'Co-Author'
date: '2024-01-15'
lang: en
description: 'Book description for catalogs.'
rights: 'Copyright © 2024'
publisher: 'Example Publishing'
---

Converting with Calibre CLI (ebook-convert)

# EPUB → PDF
ebook-convert book.epub book.pdf

# EPUB → MOBI (Kindle)
ebook-convert book.epub book.mobi

# EPUB → AZW3 (modern Kindle)
ebook-convert book.epub book.azw3

# DOCX → EPUB with options
ebook-convert book.docx book.epub \
  --title "My Book" \
  --authors "Author" \
  --language en \
  --cover cover.jpg \
  --output-profile tablet

# HTML → EPUB
ebook-convert page.html book.epub --no-default-epub-cover

Calibre GUI offers the same conversions visually — ideal if you prefer a graphical interface.

Creating EPUB with Python (ebooklib)

from ebooklib import epub

# 1. Create book
book = epub.EpubBook()
book.set_identifier('id-my-book-001')
book.set_title('My Ebook with Python')
book.set_language('en')
book.add_author('Your Name')

# 2. Create chapter
chapter = epub.EpubHtml(
    title='Chapter 1: Start',
    file_name='ch01.xhtml',
    lang='en'
)
chapter.content = '''<html><body>
  <h1>Chapter 1: Start</h1>
  <p>This is the content of the first chapter.</p>
  <p>You can include <strong>full HTML</strong> here.</p>
</body></html>'''

# 3. Add CSS
style = epub.EpubItem(
    uid="style",
    file_name="style/main.css",
    media_type="text/css",
    content=b'body { font-family: Georgia, serif; line-height: 1.6; }'
)
chapter.add_item(style)

# 4. Add to book
book.add_item(chapter)
book.add_item(style)

# 5. Define table of contents and spine
book.toc = (epub.Link('ch01.xhtml', 'Chapter 1', 'ch01'),)
book.add_item(epub.EpubNcx())
book.add_item(epub.EpubNav())
book.spine = ['nav', chapter]

# 6. Save
epub.write_epub('my_ebook.epub', book)
print("EPUB generated successfully")

Validating EPUB (epubcheck)

epubcheck is the official W3C validator:

# Install (requires Java)
# Download from: https://github.com/w3c/epubcheck/releases

# Validate
java -jar epubcheck.jar book.epub

# Expected output (no errors):
# Errors: 0   Warnings: 0   Infos: 0

Common errors:

• OPF001: mimetype file is not first or is compressed
• RSC-005: reference to a file not declared in the manifest
• NCX-003: missing toc.ncx file for EPUB 2 compatibility

EPUB 2 vs EPUB 3

Recommended Tools

Convert EPUB Online

For quick conversions without installing software, KaijuConverter supports EPUB as both source and destination. Convert EPUB to PDF, DOCX, or between ebook formats directly in your browser.

Related conversions

Document conversions that follow this topic naturally:

• PDF to DOCX
• DOCX to PDF
• MD to PDF
• HTML to PDF
• ODT to PDF
• PDF to TXT