📖 Chapter 90: HTML for E-Books (EPUB 3)

Building an End-to-End Published E-Book

Full-Scale Production Project: Architecting, Authoring, Validating, and Packaging a Complete Multi-Chapter Technical E-Book

LEARNING OBJECTIVES ⌵

Synthesize all core EPUB 3 specifications into a publication-ready, commercial-grade digital book.
Construct the entire container file hierarchy from mimetype to META-INF/container.xml and package.opf.
Author structured XHTML content documents featuring MathML formulas, pop-up footnotes, sidebars, and DPUB-ARIA landmarks.
Implement production-grade CSS supporting fluid reflow, dark mode safety, and pagination break controls.
Build a tri-part Navigation Document (nav.xhtml) with TOC, Landmarks, and Print Page-Lists.
Execute automated packaging and verify 100% compliance with epubcheck and Ace by DAISY.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Assembling an EPUB 3 publication is like crafting a mechanical Swiss chronometer. Each individual gear—strict XML syntax, Dublin Core metadata, semantic DPUB-ARIA landmarks, pagination-safe CSS, uncompressed byte offsets, and navigation trees—must mesh with microscopic precision.

+-----------------------------------------------------------------------------------+
|                        END-TO-END PUBLISHING PIPELINE                             |
+-----------------------------------------------------------------------------------+
  [Step 1: Scaffolding]    -> mimetype (uncompressed) + META-INF/container.xml
            |
  [Step 2: Content XHTML]  -> Strict XHTML5 + MathML + Pop-up Footnotes + ARIA Roles
            |
  [Step 3: Styling Engine] -> Fluid CSS3 + Break Controls + Dark Mode Safety
            |
  [Step 4: Navigation]     -> nav.xhtml (TOC + Landmarks + Page-List)
            |
  [Step 5: Master OPF]     -> package.opf (Metadata + Manifest + Spine)
            |
  [Step 6: Packaging & QA] -> OCF Zip -> EpubCheck Validation -> Ace DAISY Audit
            |
            v
  [DISTRIBUTION: Apple Books, Amazon Kindle KFX, Kobo, Thorium Reader]

When every piece is built according to open W3C standards, your book glides effortlessly across Apple Books on iOS, Kindle Paperwhite on E-Ink, and screen readers on Windows with flawless typographic elegance.

Technical Deep Dive & Specifications

Complete Project File Tree Architecture

Below is the production filesystem layout for our complete technical book, "Architectures of Resilient Systems":

resilient-systems-project/
├── mimetype                          <- Exact 20 bytes: application/epub+zip
├── META-INF/
│   └── container.xml                 <- Container bootstrap pointer
└── EPUB/
    ├── package.opf                   <- Master Package Document
    ├── text/
    │   ├── cover.xhtml               <- Book Cover Page
    │   ├── nav.xhtml                 <- Primary Navigation Document
    │   ├── ch01_concurrency.xhtml    <- Chapter 1 (Content + MathML + Footnotes)
    │   ├── ch02_consensus.xhtml      <- Chapter 2 (Content + Complex Tables)
    │   └── glossary.xhtml            <- Glossary of Terms
    ├── styles/
    │   └── epub.css                  <- Production Paged Media Stylesheet
    └── images/
        ├── cover.svg                 <- Vector Cover Artwork
        └── raft_diagram.svg          <- Accessible Architectural SVG

💻 Interactive Code Playground

Let's examine the core files that make up this complete publication.

1. `META-INF/container.xml`

2. `EPUB/package.opf` (Master Control Center)

3. `EPUB/text/ch01_concurrency.xhtml` (Chapter 1)

4. `EPUB/text/nav.xhtml` (Navigation Document)

5. `EPUB/styles/epub.css` (Hardened Typography)

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<?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" 
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      lang="en" xml:lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Chapter 1: Formal Concurrency Models</title>
  <link rel="stylesheet" type="text/css" href="../styles/epub.css" />
</head>
<body epub:type="bodymatter">
  <section epub:type="chapter" role="doc-chapter" aria-labelledby="ch1-heading">
    <header>
      <p class="chapter-label">Chapter 1</p>
      <h1 id="ch1-heading">Formal Concurrency Models</h1>
    </header>

<p class="lead">
      Concurrent execution models govern how multiple computation threads interleave memory operations without corrupting state invariants<a href="#fn-atomic" id="ref-atomic" epub:type="noteref" role="doc-noteref" class="footnote-ref">1</a>.
    </p>

<h2>1.1 Amdahl's Law Formulation</h2>
    <p>
      The theoretical speedup of a program utilizing multiple processing cores is mathematically bounded by:
    </p>

<div class="math-block">
      <m:math display="block">
        <m:mrow>
          <m:mi>S</m:mi>
          <m:mo stretchy="false">(</m:mo>
          <m:mi>s</m:mi>
          <m:mo stretchy="false">)</m:mo>
          <m:mo>=</m:mo>
          <m:mfrac>
            <m:mn>1</m:mn>
            <m:mrow>
              <m:mo stretchy="false">(</m:mo>
              <m:mn>1</m:mn>
              <m:mo>−</m:mo>
              <m:mi>p</m:mi>
              <m:mo stretchy="false">)</m:mo>
              <m:mo>+</m:mo>
              <m:mfrac>
                <m:mi>p</m:mi>
                <m:mi>s</m:mi>
              </m:mfrac>
            </m:mrow>
          </m:mfrac>
        </m:mrow>
      </m:math>
    </div>

<aside epub:type="sidebar" role="complementary" aria-labelledby="callout-heading" class="callout">
      <h3 id="callout-heading">Key Takeaway</h3>
      <p>
        No matter how many parallel cores are added, the speedup is strictly limited by the sequential fraction (<em>1 - p</em>).
      </p>
    </aside>

<section epub:type="footnotes" role="doc-footnotes" class="footnotes-wrapper">
      <hr />
      <aside id="fn-atomic" epub:type="footnote" role="doc-footnote" class="footnote">
        <p>
          <strong>1.</strong> Linearizability guarantees that all operations appear to execute atomically at a specific linearization point.
          <a href="#ref-atomic" role="doc-backlink" aria-label="Return to reading text">↩</a>
        </p>
      </aside>
    </section>
  </section>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

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

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" 
         unique-identifier="pub-id" 
         version="3.0" 
         prefix="rendition: http://www.idpf.org/vocab/rendition/# schema: http://schema.org/">

  <!-- 1. METADATA & ACCESSIBILITY -->
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier id="pub-id">urn:uuid:7c8b9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e</dc:identifier>
    <dc:title>Architectures of Resilient Systems</dc:title>
    <dc:creator id="aut">Dr. Marcus Vance</dc:creator>
    <meta refines="#aut" property="role" scheme="marc:relators">aut</meta>
    <dc:publisher>Distributed Systems Press</dc:publisher>
    <dc:language>en-US</dc:language>
    <meta property="dcterms:modified">2026-08-20T18:00:00Z</meta>

    <!-- Schema.org Accessibility Metadata -->
    <meta property="schema:accessMode">textual</meta>
    <meta property="schema:accessMode">visual</meta>
    <meta property="schema:accessModeSufficient">textual,visual</meta>
    <meta property="schema:accessibilityFeature">structuralNavigation</meta>
    <meta property="schema:accessibilityFeature">alternativeText</meta>
    <meta property="schema:accessibilityFeature">tableOfContents</meta>
    <meta property="schema:accessibilityHazard">none</meta>
    <meta property="schema:accessibilitySummary">Conforms to WCAG 2.1 AA and EPUB Accessibility 1.1.</meta>
  </metadata>

  <!-- 2. MANIFEST -->
  <manifest>
    <item id="nav" href="text/nav.xhtml" media-type="application/xhtml+xml" properties="nav" />
    <item id="cover" href="text/cover.xhtml" media-type="application/xhtml+xml" />
    <item id="ch01" href="text/ch01_concurrency.xhtml" media-type="application/xhtml+xml" properties="mathml" />
    <item id="ch02" href="text/ch02_consensus.xhtml" media-type="application/xhtml+xml" properties="svg" />
    <item id="glossary" href="text/glossary.xhtml" media-type="application/xhtml+xml" />
    <item id="css" href="styles/epub.css" media-type="text/css" />
    <item id="cover-img" href="images/cover.svg" media-type="image/svg+xml" properties="cover-image" />
    <item id="diagram-raft" href="images/raft_diagram.svg" media-type="image/svg+xml" />
  </manifest>

  <!-- 3. SPINE -->
  <spine>
    <itemref idref="cover" linear="no" />
    <itemref idref="nav" />
    <itemref idref="ch01" />
    <itemref idref="ch02" />
    <itemref idref="glossary" />
  </spine>

</package>

/* Core Layout & Hyphenation */
html, body {
  margin: 0;
  padding: 0;
  font-size: 100%;
  line-height: 1.5;
  hyphens: auto;
  -webkit-hyphens: auto;
}

/* Headings with Orphan Prevention */
h1, h2, h3 {
  line-height: 1.2;
  break-after: avoid;
  page-break-after: avoid;
}

h1 {
  font-size: 1.8rem;
  margin-top: 1.5em;
  margin-bottom: 0.8em;
  text-align: center;
  break-before: page;
  page-break-before: always;
}

p {
  margin-top: 0;
  margin-bottom: 0;
  text-indent: 1.5em;
  text-align: justify;
  orphans: 2;
  widows: 2;
}

h1 + p, h2 + p, p.lead {
  text-indent: 0;
}

/* Theme-Safe Callout Box */
aside.callout {
  margin: 1.5em 0;
  padding: 1em;
  border-left: 4px solid #0284c7;
  background-color: rgba(2, 132, 199, 0.08);
  border-radius: 0 4px 4px 0;
  break-inside: avoid;
  page-break-inside: avoid;
}

/* MathML formatting */
.math-block {
  text-align: center;
  margin: 1.5em 0;
  break-inside: avoid;
}

🏋️ Hands-On Exercise

🎯 The Challenge: Author and Integrate Chapter 2

Instructions:

Create EPUB/text/ch02_consensus.xhtml containing:
- Proper XHTML prologue, namespaces (xmlns, xmlns:epub), and lang tags.
- A chapter header for "Chapter 2: Distributed Consensus & Raft".
- A section containing an accessible <figure> wrapping ../images/raft_diagram.svg with alt text and a <figcaption>.
Connect ch02_consensus.xhtml into the package.opf <manifest> and <spine>.
Update nav.xhtml to include Chapter 2 in the Table of Contents.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<?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" 
      lang="en" xml:lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Chapter 2: Distributed Consensus &amp; Raft</title>
  <link rel="stylesheet" type="text/css" href="../styles/epub.css" />
</head>
<body epub:type="bodymatter">
  <section epub:type="chapter" role="doc-chapter" aria-labelledby="ch2-title">
    <header>
      <p class="chapter-label">Chapter 2</p>
      <h1 id="ch2-title">Distributed Consensus &amp; Raft</h1>
    </header>

    <p class="lead">
      The Raft consensus algorithm decomposes state machine replication into three distinct subproblems: Leader Election, Log Replication, and Safety.
    </p>

    <figure class="diagram-figure">
      <img src="../images/raft_diagram.svg" 
           alt="State machine diagram showing transitions between Follower, Candidate, and Leader roles in Raft" />
      <figcaption>Figure 2.1: Raft Node State Transition Diagram</figcaption>
    </figure>

    <p>
      At any given time, every node exists in one of three states: Follower, Candidate, or Leader.
    </p>
  </section>
</body>
</html>

Why this works:

Strict XML well-formedness: escaped &, self-closing <img>, and explicit namespaces.
Accessible image structure with detailed alternative text and semantic <figcaption>.

⚠️ Common Pitfalls

Mismatched Manifest IDs: Declaring id="chapter-2" in <manifest> but referencing idref="ch02" in <spine>. This triggers an instant OPF-014 fatal validation failure.
Forgetting to Update dcterms:modified: Every time you package a new build of an EPUB, you must update the <meta property="dcterms:modified"> timestamp to current UTC time.
Unescaped Special Characters in Titles: Writing <dc:title>Design & Architecture</dc:title> in package.opf will crash XML parsers. It must be written as Design & Architecture.

💡 Pro Tips

Automate the Build Pipeline: Write an npm run build script that runs XML linting, checks MathML validity, packages the OCF archive, and executes epubcheck and ace in a single command.
Multi-Store Testing: Before commercial distribution, test your compiled .epub in:
- Apple Books (macOS / iOS)
- Kindle Previewer 3 (Amazon KF8 / KFX)
- Thorium Reader (W3C Reference Desktop Reader)

📌 Key Takeaways

EPUB 3 represents a complete, self-contained offline web application packaged inside an OCF-compliant ZIP archive.
Content documents must adhere to strict XHTML5, lowercase casing, escaped entities, and self-closing tags.
Semantics should be doubly enriched using epub:type and DPUB-ARIA role="doc-*" attributes.
The package.opf file acts as the master manifest, declaring all assets and defining the spine reading flow.
The nav.xhtml document provides the Table of Contents, reader Landmarks, and physical Print Page Lists.
Build pipelines should enforce automated validation with epubcheck and Ace by DAISY.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What is the correct sequence of tools to validate an EPUB 3 publication for both technical specification compliance and accessibility before publishing?

Topic: HTML Fundamentals

? Question 2 / 3

Why is `linear="no"` assigned to the cover page in `<spine>`?

Topic: HTML Fundamentals

? Question 3 / 3

Which file format is used for the Navigation Document in modern EPUB 3?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Complete Project File Tree Architecture

💻 Interactive Code Playground

1. META-INF/container.xml

2. EPUB/package.opf (Master Control Center)

3. EPUB/text/ch01_concurrency.xhtml (Chapter 1)

4. EPUB/text/nav.xhtml (Navigation Document)

5. EPUB/styles/epub.css (Hardened Typography)

🏋️ Hands-On Exercise

🎯 The Challenge: Author and Integrate Chapter 2

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the correct sequence of tools to validate an EPUB 3 publication for both technical specification compliance and accessibility before publishing?

Why is linear="no" assigned to the cover page in <spine>?

Which file format is used for the Navigation Document in modern EPUB 3?

1. `META-INF/container.xml`

2. `EPUB/package.opf` (Master Control Center)

3. `EPUB/text/ch01_concurrency.xhtml` (Chapter 1)

4. `EPUB/text/nav.xhtml` (Navigation Document)

5. `EPUB/styles/epub.css` (Hardened Typography)

Why is `linear="no"` assigned to the cover page in `<spine>`?