High Level Structural Patterns
Section should contain high-level structural patterns for common formatting situations.
Major structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a
Individual items in a larger collection (like a poem in a poetry collection) are contained in a
Collections of very short work, like collections of poems, have all of their content in a single file, and
break-*CSS is added to generate page breaks between items:
<articles>elements that have titles, the first child element is an
<h6>element, or a
<header>element containing the section’s title.
“Recomposability” is the concept of generating a single structurally-correct HTML5 file out of an epub file. All Standard Ebooks are recomposable.
XHTML files that contain
<articles>elements that are semantic children of
<articles>elements in other files, are wrapped in stubs of all parent
<articles>elements, up to the root.
Each such included parent element has the identical
epub:typeattributes of its real counterpart.
Consider a book that contains several top-level subdivisions: Books 1–4, with each book having 3 parts, and each part having 10 chapters. Below is an example of three files demonstrating the structure necessary to achieve recomposability:
Book 1 (
Book 1, Part 2 (
Book 1, Part 2, Chapter 3 (
<h6>elements are used for headers of sections that are structural divisions of a document, i.e., divisions that appear in the table of contents.
<h6>elements are not used for headers of components that are not in the table of contents. For example, they are not used to mark up the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.
A section containing an
<h6>appears in the table of contents.
The book’s title is implicitly at the
<h1>level, even if
<h1>is not present in the ebook. An
<h1>element is only present if the ebook contains a half title page. Because of the implicit
<h1>, all other sections begin at
<h6>element uses the correct number for the section’s heading level in the overall book, not the section’s heading level in the individual file. For example, given an ebook with a file named
Consider this example for the file
<h6>element has a direct parent
Sections without titles:
Sections with titles but no ordinal (i.e. chapter) numbers:
Sections with titles and ordinal (i.e. chapter) numbers:
Sections titles and subtitles but no ordinal (i.e. chapter) numbers:
Sections that have a non-unique title, but that are required to be identifed in the ToC with a unique title (e.g., multiple poems identified as “Sonnet” in the body matter, which require their ToC entry to contain the poem’s first line to differentiate them):
Sections that require titles, but that are not in the table of contents:
Half title pages without subtitles:
Half title pages with subtitles:
Bridgeheads are sections in a chapter header that give an abstract or summary of the following chapter. They may be in prose or in a short list with clauses separated by em dashes.
The last clause in a bridgehead ends in appropriate punctuation, like a period.
Bridgeheads have the following CSS and HTML structure:
Dedications are typically full-page, centered on the page for ereaders that support advanced CSS. For all other ereaders, the dedication is horizontally centered with a small margin above it.
All dedications include this base CSS:
Dedications are frequently styled uniquely by the authors. Therefore Standard Ebooks producers have freedom to style dedications to match page scans, for example by including small caps, different font sizes, alignments, etc.
All epigraphs include this CSS:
Epigraphs in section headers
Epigraphs in section headers have the quote source in a
<cite>element set in small caps, without a leading em-dash and without a trailing period.
In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers:
In full-page epigraphs, the epigraph is centered on the page for ereaders that support advanced CSS. For all other ereaders, the epigraph is horizontally centered with a small margin above it.
Full-page epigraphs that contain multiple quotations are represented by multiple
In addition to the CSS used for all epigraphs, this additional CSS is included for full-page epigraphs:
Poetry, verse, and songs
Unfortunately there’s no great way to semantically format poetry in HTML. As such, unrelated elements are conscripted for use in poetry.
A stanza is represented by a
<p>element styled with this CSS:
Each stanza contains
<span>elements, each one representing a line in the stanza, styled with this CSS:
<span>line is followed by a
<br/>element, except for the last line in a stanza, styled with this CSS:
<span>lines have the
i1class. Do not use
nbspfor indentation. Indenting to different levels is done by incrementing the class to
i3, and so on, and including the appropriate CSS.
Poems, songs, and verse that are shorter part of a longer work, like a novel, are wrapped in a
The parent element of poetry, verse, or song, has the semantic inflection of
If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipses (
⋮or U+22EE) in a
<span class="elision">element styled with this CSS:
Note that below we include CSS for the
.i2 class, even though it’s not used in the example. It’s included to demonstrate how to adjust the CSS for indentation levels after the first.
Plays and drama
Dialog in plays is structured using
<tr>is either a block of dialog or a standalone stage direction.
Works that are plays or that contain sections of dramatic dialog have this core CSS:
The first child of a row of dialog is a
<td>element with the semantic inflection of
The second child of a row of dialog is a
<td>element containing the actual dialog. Elements that contain only one line of dialog do not have a block-level child (like
When several personas speak at once, or a group of personas (“The Actors”) speaks at once, the containing
<tr>element has the
togetherclass, and the first
<td>child has a
rowspanattribute corresponding to the number of lines spoken together.
Stage direction rows
The first child of a row of stage direction is an empty
The second child of a row of dialog is a
<td>element containing the stage direction.
Stage direction is wrapped in an
Stage directions that are included from a different edition additionally have the
class="editorial"attribute, with this additional CSS:
Personas mentioned in stage direction are wrapped in a
Stage direction in shorthand (for example,
Large French window, R. 3 E.) is wrapped in an
<abbr epub:type="z3998:stage-direction">element, with this additional CSS:
Works that are complete plays
The top-level element (usually
<body>) has the
<section>elements containing at least one
<table>for dialog, and optionally containing an act title and other top-level stage direction.
Introductory or high-level stage direction is presented using
<p>elements outside of the dialog table.
Dramatis personae are presented as a
<ul>element listing the characters.
Letters require particular attention to styling and semantic inflection. Letters may not exactly match the formatting in the source scans, but they are in visual sympathy with the source.
Letters are wrapped in a
<blockquote>element with the appropriate semantic inflection, usually
Parts of a letter prior to the body of the letter, for example the location where it is written, the date, and the salutation, are wrapped in a
If there is only a salutation and no other header content, the
<header>element is omitted.
The location and date of a letter have the semantic inflection of
se:letter.dateline. Dates are in a
<time>element with a computer-readable date.
The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of
The first line of a letter after the salutation is not indented.
Salutations that are within the first line of the letter are wrapped in a
<span epub:type="z3998:salutation">element (or a
<b epub:type="z3998:salutation">element if small-caps are desired).
The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of
z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a
Parts of a letter after the body of the letter, for example the signature or postscript, are wrapped in a
<footer>element has the following CSS:
The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of
The sender’s name has semantic inflection of
z3998:sender. If the name appears to be a signature to the letter, it has the
signatureclass and the corresponding
Postscripts have the semantic inflection of
z3998:postscriptand the following CSS:
<img>elements have an
altattribute that uses prose to describe the image in detail; this is what screen reading software will read aloud.
altattribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book.
altattribute is one or more complete sentences ended with periods or other appropriate punctuation. It is not composed of sentence fragments or complete sentences without ending punctuation.
altattribute is not necessarily the same as text in the image’s sibling
<figcaption>element, if one is present.
<img>elements have semantic inflection denoting the type of image. Common values are
<img>element whose image is black-on-white line art (i.e. exactly two colors, not grayscale!) are PNG files with a transparent background. They have the
<img>elements that are meant to be aligned on the block level or displayed as full-page images are contained in a parent
<figure>element, with an optional
When contained in a
<img>element does not have an
idattribute; instead the
<figure>element has the
<figcaption>element containing a concise context-dependent caption may follow the
<img>element within a
<figure>element. This caption depends on the surrounding context, and is not necessarily (or even ideally) identical to the
All figure elements, regardless of positioning, have this CSS:
<figure>elements that are meant to be displayed as full-page images have the
full-pageclass and this additional CSS:
<figure>elements that meant to be aligned block-level with the text have this additional CSS:
List of Illustrations (the LoI)
If an ebook has any illustrations that are major structural components of the work (even just one!), then the ebook includes an
loi.xhtml file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.
The LoI is an XHTML file named
The LoI file has the
The LoI only contains links to images that are major structural components of the work.
An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.
An illustration is not a major structural components if, for example: it is a drawing used to represent a person’s signature, like an X mark; it is an inline drawing representing text in alien languages; it is a drawing used as a layout element to illustrate forms, tables, or diagrams.
The LoI file contains a single
<section id="loi" epub:type="loi">element, which in turn contains an
<h2 epub:type="title">List of Illustrations</h2>element, followed by a
<nav epub:type="loi">element containing an
<ol>element, which in turn contains list items representing the images.
If an image listed in the LoI has a
<figcaption>element, then that caption is used in the anchor text for that LoI entry. If not, the image’s
altattribute is used. If the
<figcaption>element is too long for a concise LoI entry, the
altattribute is used instead.
Links to the images go directly to the image’s corresponding
idhashes, not just the top of the containing file.
Ebooks do not have footnotes, only endnotes. Footnotes are instead converted to endnotes.
“Ibid.” is a Latinism commonly used in endnotes to indicate that the source for a quotation or reference is the same as the last-mentioned source.
When the last-mentioned source is in the previous endnote, Ibid. is replaced by the full reference; otherwise Ibid. is left as-is. Since ebooks use popup endnotes, “Ibid.” becomes meaningless without context.
The noteref is the superscripted number in the body text that links to the endnote at the end of the book.
Endnotes are referenced in the text by an
<a>element with the semantic inflection
Noterefs point directly to the corresponding endnote
<li>element in the endnotes file.
Noterefs have an
nis identical to the endnote number.
The text of the noteref is the endnote number.
If located at the end of a sentence, noterefs are placed after ending punctuation.
If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the noteref is placed outside the quotation marks.
The endnotes file
Endnotes are in an XHTML file named
The endnotes file has the
The endnotes file contains a single
<section id="endnotes" epub:type="endnotes">element, which in turn contains an
<h2 epub:type="title">Endnotes</h2>element, followed by an
<ol>element containing list items representing the endnotes.
idattribute is in sequential ascending order.
An endnote is an
<li id="note-n" epub:type="endnote">element containing one or more block-level text elements and one backlink element.
Each endnote’s contains a backlink, which has the semantic inflection
backlink, contains the text
↩, and has the
hrefattribute pointing to the corresponding noteref hash.
In endnotes where the last block-level element is a
<p>element, the backlink goes at the end of the
<p>element, preceded by exactly one space.
In endnotes where the last block-level element is verse, quotation, or otherwise not plain prose text, the backlink goes in its own
<p>element following the last block-level element in the endnote.
Endnotes with ending citations have those citations are wrapped in a
<cite>element, including any em-dashes. A space follows the
<cite>element, before the backlink.
Glossaries may be included if there are a large number of domain-specific terms that are unlikely to be in a common dictionary, or which have unique meanings to the work.
Glossaries follow the EPUB Dictionaries and Glossaries 1.0 spec.
The glossary search key map file
When including a glossary, a search key map file is required according to the EPUB Dictionaries and Glossaries 1.0 spec.
The search key map file is named
The search key map file contains
<value>elements describing all stemmed variations of the parent search term that occur in the ebook. Variations that don't occur in the ebook are excluded.
<match>element only has one
<value>element is removed in favor of
The glossary file
Glossaries are in an XHTML file named
The glossary file has the
The glossary file contains a single
<section id="glossary" epub:type="glossary">element, which may contain a title, followed by a
<dl>element containing the glossary entries. While the EPUB glossaries spec suggests the
epub:typeattribute be placed on the
<dl>element, in a Standard Ebook it is placed on the
All glossaries include the following CSS:
<dl>element contains sets of
<dt>element contains a single
<dfn>element, which in turn contains the term to be defined.
<dd>element appears after one or more
<dt>elements, and contains the definition for the preceding
<dt>element(s). It must contain at least one block-level child, usually
<dt>may appear more than once for a single glossary entry, if different variations of a term have the same definition.