Skip to main content

Every Paragraph Gets an Address Before the Chapter Opens

Updated 6 min readMarkdown

An EPUB chapter is a small HTML document, written by a publisher's toolchain, and it is almost never written for the situation it ends up in: displayed inside a reader, restyled on demand, with any paragraph reachable by a tap, a search hit, or a bookmark. Before a chapter is shown, the reader rewrites it just enough to make that possible. The rewriting is small, and deliberately so — three passes over the bytes, plus a stylesheet the reader adds at display time. Nothing in the chapter's own text is touched.

XHTML in the file, HTML in the browser

EPUB content documents are XHTML by specification. The reader serves them to the browser as HTML. That mismatch is usually harmless, until it is not.

In XHTML, an empty element can be written self-closed: <pre/>, <div/>, <p/>. In HTML, the slash on a non-void element means nothing — the parser ignores it and treats the tag as an opening tag that never closes. Everything after it becomes its child. One book in the test set had a single <pre/> early in a chapter; the browser folded the rest of the chapter inside it — 561 child elements, 2,076 descendants, 543 paragraphs — and applied the pre element's default styling to all of it: monospace type, preserved whitespace, one endless line. The chapter measured 8,933 pixels wide where it should have been 837. It was unreadable, and nothing in the text itself was wrong.

The reader's fix is mechanical: before serving a chapter, every self-closed tag on a non-void element is rewritten with an explicit closing tag, <pre/> to <pre></pre>. Void elements — br, img, hr, meta, link, and the rest — are left alone, because in HTML they are already self-closing by definition, and rewriting them would add a phantom second element. SVG and MathML self-closing tags need no special case either: <path></path> means the same thing inside SVG. In a 28-book sample, 10 books contained at least one of these stray self-closed tags.

Dropping the doctype on purpose

The same pass strips the XML declaration and the doctype from the top of the document. That sounds like vandalism, and it is done for a concrete reason.

Without a doctype, the browser renders in quirks mode. In quirks mode, a body{height:100%} rule resolves against the viewport directly. In standards mode, that same rule needs an html{height:100%} above it to have anything to resolve against, and many EPUBs define the first without the second. Full-page images — covers, plates, illustrated pages that are meant to fill the screen — broke: the height chain snapped, the image fell back to its natural size, and the reader's height probe stopped working.

An earlier version of the pipeline got this behavior for free and nobody noticed why. It parsed chapters with a real HTML parser and re-serialized them, and serialization dropped the doctype. When the pipeline was rewritten to work directly on the bytes, the doctype survived, standards mode came back, and the full-page images broke. The fix was to reproduce the old side effect deliberately: strip the declaration and the doctype, keep quirks mode. A cleaner-looking alternative — injecting html{height:100%} into the head — was tried and rejected, because it only fixed books that set height on the body, not books that set it on the image itself. The doctype strip covers both.

A line number is not a line of text

Once the document is safe to render, every block element gets a number: p, div, h1 through h5, plus nav and li. Each opening tag gains a lineid attribute, counted up from zero in document order, and an id like zigo42 — unless the element already has an id, in which case the publisher's anchor is left untouched and only the lineid is added.

The number is an address, not a count of anything visible. Empty blocks get numbers too. Container div elements get numbers too. An earlier version only numbered blocks that contained text, and it was slower; the current version numbers every matching tag and lets the front end ignore the empty ones. That looseness is a trade: the numbering pass is a single regular-expression substitution over the raw bytes, about half a millisecond per chapter against roughly eleven for the old parser round-trip, and the cost is a few numbers nobody will ever click.

The numbers are per chapter, not per book. The same lineid value in two chapters means two different paragraphs. Anything that points at a paragraph — a bookmark, a highlight, a search result — has to carry the chapter with it, or it points at the wrong place.

The order of the two passes is not negotiable

The numbering pass runs before the self-closing fix, and reversing them would silently corrupt every address in the chapter.

The numbering pass deliberately skips self-closed tags: <p/> has no content to address, so it gets no number. If the self-closing fix ran first, that same tag would become <p></p> — an ordinary empty paragraph — and would take a number. Every paragraph after it would shift by one. Stored translations, bookmarks, and position data keyed to the old numbers would land on the wrong paragraph, with no error anywhere to show for it. The pipeline keeps the passes in this order because the numbers are a contract with data written earlier, not just decoration on the page.

For the same reason, the whole transformation happens when the book is opened, not when it is displayed. Every chapter in the book is processed once, up front, so the numbers are stable for the entire reading session. A chapter served twice carries the same addresses both times.

The publisher's styles stay; the reader's theme sits on top

One thing the pipeline does not do is clean the chapter in the sense most people expect. No publisher stylesheet is removed, no inline style is stripped, no script is taken out. The chapter keeps the publisher's typography, and the reader's theme does not replace it — it layers over it.

At display time, the reader's front end appends its own stylesheet link into the chapter document, once, guarded so it is never added twice. That sheet defines the light and dark surfaces: text and background colors for the book area, link colors in dark mode, highlight colors. Where the publisher's rules and the reader's rules collide, the cascade decides, the same way it decides everywhere else in a browser. The reader does not rewrite the publisher's CSS to win; it just adds its own sheet last and accepts the outcome.

The injected marks are the reader's private property, and they are treated that way. When a book is exported back out as an EPUB, the lineid attributes, the generated zigo ids, and the reader's stylesheet link are stripped back out, leaving the publisher's document as it was. The addresses exist only inside the reader, for as long as the book is being read.

About the author

  • Writing about ebook technology.

No comments yet. Be the first to comment.