EPUB Document Sectioning

Introduction

Some EPUBs consist of a single large Content Document. These EPUBs can be slow to render because all text and resources must be loaded to paginate and display the content. In Colibrio Reader Framework 4.0.0, we introduced a new feature called Document Sectioning to improve the performance of these EPUBs.

How to enable Document Sectioning

Starting with framework version 5.0.0, Document Sectioning is enabled by default. For earlier versions, enable it by setting IEpubReaderPublicationOptions.documentSectioningOptions.enabled to true. Colibrio offers default document sectioning options suitable for most EPUBs, but sometimes you may need to set EPUB-specific options. See the Configuration section below for details.

Effects of Document Sectioning

When Document Sectioning is enabled, large Content Documents are divided into smaller sections. This allows them to load and render faster because each section can be processed and paginated individually by the framework.

Developer Perspective

From a developer's perspective, there are no side effects from enabling Document Sectioning. A Content Document divided into several sections is still considered one ReaderDocument. Locators are not affected either; they point to the same positions in the EPUB regardless of whether the documents have been sectioned.

End-User Perspective

For the end-user, a Document Sectioning break will appear as a normal page break.

Configuration

By default, the framework inserts section breaks before <h1> elements, then before <h2> elements, and finally before <h3> elements. Section breaks are not inserted if any resulting section contains fewer than 10,000 characters.

Example

For example, let's say that we have a Document with two chapters. Each chapter title headings use <h1> elements and each chapter is just over 10000 characters long. The second chapter also has a sub-chapter using a <h2> element:

The Document Sectioning algorithm starts by finding all <h1> elements. It inserts a Document Sectioning break just before “Chapter 2” because the two resulting sections each contain more than 10000 characters. Then, it searches for all <h2> elements. It does not insert a Document Sectioning break before “Sub-chapter 2.1” because at least one resulting section would have fewer than 10000 characters.

Configuring Section Break Positions with CSS Selectors

Some EPUBs use non-semantic HTML for headings, such as <div class="heading">Chapter 1</div>. For these EPUBs, you must provide custom options for document sectioning to have any effect.

Standard CSS selectors are used to define section-break positions. To create section breaks before elements with the class heading, use the following configuration:

const options: IEpubReaderPublicationOptions = {
  documentSectioningOptions: {
    enabled: true,
    algorithm: {
      type: EpubDocumentSectioningAlgorithmType.SELECTOR,
      minimumCharactersPerSection: 10000,
      selectors: [
        {
          breakPosition: SectionBreakPosition.BEFORE,
          selector: '.heading',
        }
      ]
    }
  }
}

By using these options, section breaks are inserted before any element that has the class heading, as long as the resulting sections each contain 10000 or more characters as specified by the minimumCharactersPerSection.