Structural Types

Cover Image

eISBN.jpg or any cover in the image directory should be named Cover.jpg.

Width

Cover.jpg should have a width of 1600px, unless the total aspect ratio exceeds 4 million pixels. If it does exceed 4 mil then adjust the width in increments of 20px and test.

Extension

Cover.jpg should use the file extension .jpg not .jpeg.

Color Space

The cover image should be in an RGB format.
You can check an image’s color space using sips.

sips -g space Cover.jpg | tail -n1 | awk '{print $2}'

the output should say RGB. If the output is Gray or anything else it should be converted to RGB.

Title Page

Half Title Page

Half title pages should always be removed and should never be added to an ePub. Exception to this rule is if editorial has made the request but push back is encouraged as it is redundant and customers have complained.

Full Title Page

Sometimes the title page can be built with text but for best results the title page should be exported from InDesign as a PNG and placed in the frontmatter as a full page image.

Export Title Page Image from InDesign

In Indesign, choose file->export then apply these settings:

Export PNG

  • Range: The page number
  • Page: Page should be selected
  • Image: Desired image settings

Title Page Image Transparency

It’s common for the title page to have transparency and this should be tested because there will be rendering issues with the image in color modes, biggest issue can be found in iBook’s Black Mode.
To test if an image is transparent use sips with hasAlpha.

sips -g hasAlpha titlepage.png  | cut -d':' -f2-

If there is no alpha the response will be no in the terminal.

Title Page Image Width

All title pages should have a width of 1000px if the title is a reflowable ePub.

Title Page Code Sample

Copyright Page

The copyright page should be the third frontmatter document.

Headings

Heading tags reflect a hierarchy and should therefore be used for semantic (not stylistic) purposes. Only the chapter title, part title, or frontmatter/backmatter section title should be tagged using <h1>. The next lower level heading tag would be <h2>, then <h3>, etc.

It is important to understand the concept of the HTML document outline See the spec. Always think of headings in terms of the document outline.

Since headings create an outline, heading tags should not be used for subheadings (See the spec).

For any headings that should not be included in the document outline (usually in aside elements), use <p epub:type="bridgehead"></p>. Also acceptable: <p> with .h1sub, .h2sub, or .h3sub.

Script-Specific Markup

Chapter Titles, Labels, and Numbers

As mentioned above, chapter titles should always be tagged as <h1> elements.

When a chapter has a label of some kind (e.g., “Chapter 1”, “1”, “A” “IV”, etc.) and also has a title, there is a special class to use. Follow the recommended code examples, using the .label class.

Do the same for any Section or Part title.

<!-- Chapter titled simply "Chapter 1" -->
<h1>Chapter 1</h1> <!-- Don't use .label when the label *is* the title -->

<!-- Chapter titled "Chapter 1: How We Got the New Testament" -->
<h1><span class="label">Chapter 1</span>How We Got the New Testament</h1>

<!-- Part titled "1. What Is Theology?" -->
<h1><span class="label">1</span>What Is Theology?</h1>

<!-- Section titled "Section 1: Introduction to the Study of the Bible -->
<h1><span class="label">Section 1</span>Introduction to the Study of the Bible</h1>

Parts

Whenever a book has a part structure (hierarchical groupings of related chapters), at least one special class (.top-level) should be used with any <h1> element in front, back, or body that does not belong in a part.

.top-level Example

Let's imagine we have a book with the following structure. The bolded sections should have the `.top-level` class on their `<h1>` elements.

  • Preface
  • Introduction
  • Part 1
    • Chapter 1
    • Chapter 2
  • Interlude
  • Part 2
    • Chapter 3
    • Chapter 4
  • Conclusion
  • Index

More specifically, the <section epub:type=""> and <h1> conventions would be like so:

Book Section Section Epub Type h1
Preface preface <h1 class="top-level">Preface</h1>
Introduction introduction <h1 class="top-level">Introduction</h1>
Part 1 part <h1>Part 1</h1>
Chapter 1 chapter <h1>Chapter 1</h1>
Chapter 2 chapter <h1>Chapter 2</h1>
Interlude chapter <h1 class="top-level">Interlude</h1>
Part 2 part <h1>Part 2</h1>
Chapter 3 chapter <h1>Chapter 3</h1>
Chapter 4 chapter <h1>Chapter 4</h1>
Conclusion conclusion <h1 class="top-level">Conclusion</h1>
Index index <h1 class="top-level">Index</h1>
Sub-Parts

When there are parts that consist of sub-parts, the special classes .part-1, .part-2, .part-3, .part-4, .part-5, and .part-6 exist to help you represent the book’s structural hierarchy.

Note that the numbers 1-6 here indicate hierarchy level, not sequential order! (Just like h1-6 tags.)

Sub-Parts Example

Let's imagine we have a book with the following structure.

  • Preface
  • Introduction
  • Part A
    • Part A-1
      • Chapter 1
      • Chapter 2
    • Part A-2
      • Chapter 3
  • Interlude
  • Part B
    • Chapter 4
    • Chapter 5
  • Conclusion
  • Index

In this case, the <section epub:type=""> and <h1> conventions would be like so:

Book Section Section Epub Type h1
Preface preface <h1 class="top-level">Preface</h1>
Introduction introduction <h1 class="top-level">Introduction</h1>
Part A part <h1 class="part-1">Part A</h1>
Part A-1 part <h1 class="part-2">Part A-1</h1>
Chapter 1 chapter <h1>Chapter 1</h1>
Chapter 2 chapter <h1>Chapter 2</h1>
Part A-2 part <h1 class="part-2">Part A-2</h1>
Chapter 3 chapter <h1>Chapter 3</h1>
Interlude chapter <h1 class="top-level">Interlude</h1>
Part B part <h1 class="part-1">Part B</h1>
Chapter 4 chapter <h1>Chapter 4</h1>
Chapter 5 chapter <h1>Chapter 5</h1>
Conclusion conclusion <h1 class="top-level">Conclusion</h1>
Index index <h1 class="top-level">Index</h1>

Page Breaks

Pages should be marked with an <a> element and the EPUB pagebreak type.

<span epub:type="pagebreak" id="pageX" title="X"></span>

EPUB pagebreak tags are inserted before all of the text on the corresponding source page, and for our team, they must follow these guidelines:

  • not in h1-6 but above
  • not breaking Scripture references
  • not as direct children of <ol>, <ul>, <dl>, or <table> (HTML syntax rules)
    <!-- Above headings -->
    <a epub:type="pagebreak" id="page123" title="123"></a>
    <h1>My Heading</h1>

Notes

Footnotes, rearnotes or any kind of notes found in content must back link regardless if they exist in the same file or another file as this is a channel requirement.
The corresponding note content should be placed in an epub:type="footnotes" section, either in a <footer> in each chapter file or in a backmatter file.
File names must always be included in the href attributes of both the footnote link and backlink, even for <footer>-based footnotes.

Note indicator:
	<a id="endnote-backlink-2-1" href="SC03_backmatter01.xhtml#endnote-2-1" class="superscript">1</a>

Note (in backmatter):
	<p class="note"><a href="SC02_chapter02.xhtml#endnote-backlink-2-1">1.</a> Note content ... </p>

Indexes

See the Indexes section.

Bibliographies

Each bibliography in the work should be tagged with <section> and the appropriate EPUB bibliography type. If a bibliography appears after the final chapter, it should be placed in a backmatter document.

Keep in mind that true bibliographies contain only sources that were actually used/cited in the work. Therefore the bibliography-specific epub:type attributes should not be used for ‘recommended reading’-type lists.

Each entry in a bibliography should be tagged with <p epub:type="biblioentry" class="hang">.

<!-- Separate file, in <body> -->
<section epub:type="bibliography">
  <h1>Bibliography</h1>
  <p epub:type="biblioentry" class="hang">Entry text.</p>
  <!-- One <p epub:type="biblioentry" class="hang"> for every entry -->
</section>

<!-- With chapter, inside the chapter <section>-->
<section epub:type="bibliography">
  <!-- the heading here is not always <h2> -->
  <!-- it should instead follow the document outline -->
  <h2>Bibliography</h2>
  <p epub:type="biblioentry" class="hang">Entry text.</p>
  <!-- One <p epub:type="biblioentry" class="hang"> for every entry -->
</section>

Abbreviations and Glossaries

Glossaries and abbreviation sections should receive the glossary EPUB type.

Glossary terms must be nested in a <dl> element and tagged according to the recommendations here.

<section epub:type="glossary">
  <!-- <dl> must be a child of <section epub:type="glossary"> -->
  <dl>
    <!-- The <dt> tag receives "glossterm" -->
    <dt epub:type="glossterm">
      <!-- The term or abbreviation itself must be tagged with <dfn> -->
      <dfn>The term</dfn>
    </dt>
    <!-- The definition/full term is tagged with <dd> and "glossdef" -->
    <dd epub:type="glossdef">The definition</dd>
    <!-- etc., for each term -->
  </dl>
</section>

Sub-sections

Since the only allowable children of <dl> are <dt> and <dd>, headings and page numbers should be children of the glossary section.

This means that any pagebreaks and headings must be outside of the <dl> element. Simply use separate <dl> elements as shown in the example.

<!-- Separate sections and page break examples -->
<section epub:type="glossary">
  <span epub:type="pagebreak" id="pagexv" title="xv"></span>
  <h1>Abbreviations</h1>
  <h2>Periodicals, Reference Works, and Serials</h2>
  <dl class="abbr-list">
    <dt epub:type="glossterm">
      <dfn>AB</dfn>
    </dt>
    <dd epub:type="glossdef">Anchor Bible</dd>
    <!-- etc. -->
  </dl>

  <span epub:type="pagebreak" id="pagexvi" title="xvi"></span>
  <h2>Ancient Works</h2>
  <h3>Pseudepigraphical Books</h3>
  <dl class="abbr-list">
    <dt epub:type="glossterm">
      <dfn><span class="italic">Apoc. Abr.</span></dfn>
    </dt>
    <dd epub:type="glossdef"><span class="italic">Apocalypse of Abraham</span></dd>
    <!-- etc. -->
  </dl>
</section>

Abbreviation Lists

Abbreviation lists should appear wherever they appear in the content, and the only additional requirement beyond the standard EPUB and HTML markup is that the <dl> element receive class="abbr-list". This simply applies different styling to abbreviation lists than to actual glossaries.

<section epub:type="glossary">
  <h1>Abbreviations</h1>
  <dl class="abbr-list">

Abbreviation Terms

Abbreviation terms must also be tagged throughout the content and should follow the HTML specification. See Abbreviations.

<abbr title="Abbreviation Definition">ABBRD</abbr>

Actual Glossaries

Actual glossaries (not abbreviation sections) should also appear wherever they appear in the content, and they must each have a unique <id> on the <dt> element, like <dt id="glossterm-1" epub:type="glossterm">.

Corresponding terms in the content documents are to be linked to the glossary according to the recommended code in the documentation below.

Glossary Links

Glossary terms appearing in the work are to be linked to the glossary document using <a> with epub:type="noteref.

<a epub:type="noteref" href="[filename]_glossary.xhtml#glossterm-376">Old Testament</a>