ai. epub tutorial. 2026-08-02

By Xah Lee. Date: 2026-07-25.

2026-08-02

write a tutorial of epub for people already know html css

ai answer

EPUB Tutorial for HTML/CSS Developers

EPUB is essentially a packaged website optimized for ebooks. If you already know HTML and CSS, you already know ~80% of what you need. The rest is packaging rules, a few metadata files, XHTML discipline, and awareness of reading-system limitations.

Current standard is EPUB 3 (3.3 is a W3C Recommendation; 3.4 is in progress). Content uses the XHTML serialization of HTML5 + CSS (from the CSS Snapshot) + optional SVG, MathML, media, and limited JavaScript.

1. Core Mental Model

An .epub file is a ZIP archive with a strict internal structure:

mybook.epub
├── mimetype                  ← must be first, uncompressed
├── META-INF/
│   └── container.xml         ← points to the package document
└── EPUB/                     ← or OEBPS/ (common convention)
    ├── content.opf           ← the package document (metadata + manifest + spine)
    ├── nav.xhtml             ← navigation document (required in EPUB 3)
    ├── css/
    │   └── style.css
    ├── chapter01.xhtml
    ├── chapter02.xhtml
    └── images/
        └── cover.jpg

mimetype – exact text application/epub+zip (no newline, no compression).
container.xml – tells the reading system where the package document is.
content.opf (Package Document) – the heart of the book: metadata, list of every file (manifest), and reading order (spine).
Content files are XHTML (well-formed XML), not loose HTML5.

2. Minimal Working Example

Create these files:

mimetype

application/epub+zip

META-INF/container.xml

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

EPUB/content.opf

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf"
         version="3.0"
         unique-identifier="uid"
         xml:lang="en">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier id="uid">urn:uuid:12345678-1234-1234-1234-123456789abc</dc:identifier>
    <dc:title>My First EPUB</dc:title>
    <dc:creator>Your Name</dc:creator>
    <dc:language>en</dc:language>
    <meta property="dcterms:modified">2026-08-02T21:00:00Z</meta>
  </metadata>

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

  <spine>
    <itemref idref="c1"/>
  </spine>
</package>

EPUB/nav.xhtml (required navigation document)

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

EPUB/chapter01.xhtml

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
  <title>Chapter 1</title>
  <link rel="stylesheet" type="text/css" href="css/style.css"/>
</head>
<body>
  <h1>Chapter 1</h1>
  <p>This is ordinary XHTML. Notice the XML rules.</p>
</body>
</html>

EPUB/css/style.css

body {
  font-family: Georgia, "Times New Roman", serif;
  line-height: 1.6;
  margin: 1em;
}
h1 {
  font-size: 1.8em;
  margin-bottom: 1em;
}
p {
  text-align: justify;
  margin: 0 0 1em;
  text-indent: 1.5em;
}

3. Packaging the EPUB

From the root folder that contains mimetype and META-INF:

# Correct way (mimetype must be stored, not compressed)
zip -X0 mybook.epub mimetype
zip -Xr9D mybook.epub META-INF EPUB

Or use a tool (recommended for real work):

Sigil (GUI editor)
Calibre (excellent for conversion + editing)
epubcheck (validation – mandatory)
Command-line: ebook-convert (Calibre) or Pandoc

Validate:

epubcheck mybook.epub

4. Important Differences from Web Development

Topic	Web	EPUB
Markup	HTML5 (flexible)	XHTML (must be well-formed XML)
Closing tags	Optional for many elements	Required (`<br/>`, `<img ... />`)
Namespaces	Rarely needed	Required on root (`xmlns="http://www.w3.org/1999/xhtml"`)
External resources	Fine	Almost everything must be packaged inside
CSS support	Excellent + progressive enhancement	Variable across reading systems
JavaScript	Full power	Supported but limited; many readers disable or sandbox it
Layout	Fixed or responsive as you choose	Reflowable by default (text reflows to screen size)
Units	px common	Prefer `em`, `%`, `rem`. Avoid fixed pixel layouts for reflowable books
User control	Limited	Readers expect to change font size, typeface, margins, night mode

XHTML gotchas:

Always self-close empty elements.
Attribute values must be quoted.
Use xml:lang in addition to (or instead of) lang.
No raw < or & in text (use entities).

5. CSS Best Practices for EPUB

/* Good starting point for reflowable books */
html {
  /* some readers ignore this, but it's useful */
  -webkit-text-size-adjust: 100%;
}

body {
  font-family: serif;          /* readers often override */
  line-height: 1.5–1.7;
  margin: 0 5%;                /* or use reading-system defaults */
}

/* Avoid */
body { width: 600px; }         /* breaks on phones */
p { font-size: 14px; }         /* users want to change size */
* { box-sizing: border-box; }  /* support varies */

/* Useful */
p { text-align: justify; hyphens: auto; }
img { max-width: 100%; height: auto; }
.page-break { page-break-before: always; }  /* or break-before: page; */

Fixed-layout (comics, children’s books, complex design) requires extra metadata in the OPF:

<meta property="rendition:layout">pre-paginated</meta>
<meta property="rendition:orientation">auto</meta>
<meta property="rendition:spread">none</meta>

and usually viewport meta + absolute positioning or SVG. Stick to reflowable unless you truly need pixel-perfect pages.

6. Navigation & Semantics

The nav.xhtml with epub:type="toc" is the modern table of contents.
You can also include landmarks (epub:type="landmarks") and page-list.
Use semantic HTML (<section>, <article>, <aside>, headings) + epub:type attributes for richer meaning (footnote, endnote, glossary, etc.).

Example:

<aside epub:type="footnote" id="fn1">
  <p>This is a footnote.</p>
</aside>

7. Workflow Recommendations

Write clean semantic XHTML + external CSS.
Keep chapters as separate files (better performance and navigation).
Put all resources in the EPUB folder and list every one in the manifest.
Generate a UUID for the identifier (or use ISBN).
Always run epubcheck.
Test on real devices / apps: Apple Books, Google Play Books, Kindle (via conversion), Thorium, Calibre viewer, Adobe Digital Editions.
For production: Sigil or Calibre Editor are excellent. For automation: Pandoc, Python libraries, or custom scripts that build the ZIP correctly.

8. Common Pitfalls

Forgetting to list a file in the manifest → broken book.
Compressing the mimetype file → invalid EPUB.
Using HTML5 void-element syntax without the trailing slash.
Absolute URLs or external fonts/images.
Heavy reliance on JavaScript or advanced CSS Grid/Flex without fallbacks.
Ignoring accessibility (alt text, reading order, contrast, landmarks).

Quick Start Tools

Sigil – visual EPUB editor (great for learning the structure).
Calibre – convert from HTML/Markdown, edit, convert to Kindle formats.
Pandoc – pandoc chapter*.md -o book.epub --css=style.css --toc.
epubcheck – the official validator.
Official specs: https://www.w3.org/TR/epub-33/ .

You already know the hard part (HTML + CSS). EPUB is mostly “put it in a ZIP with the right paperwork and stay XML-clean.” Once you package one successful book and validate it, the process becomes straightforward.

Happy publishing!