Reading order

Reading order

The reading order is the sequence in which files are arranged when viewing a project. File names are included in the toc.yml file in the desired reading order, and chapters can also be nested. The reading order can be set for all builds by updating the entries in the toc.yml.

The only exception to this is the figures section. Since b-ber creates figures pages dynamically during the build, you only need to include a figures-titlepage entry in the toc.yml to indicate where you'd like the figures section to be placed. Find more detailed information below.

The reading order can also be configured per-build basis by adding <type>.yml files to the _project directory, where <type> is the name of the build type (epub, mobi, reader, web, pdf, sample or xml). This allows content to be structured differently for different output formats.

YAML entries and the reading order

When you add or remove Markdown files to your project, b-ber will automatically update the toc.yml to keep everything in sync. If using multiple YAML files, b-ber will ensure that the updates only occur in the file that relates to the current build.

Setting the desired reading order

The reading order of the project will follow the order of the files listed in the toc.yml file.

Note: Do not include the file extension when changing items in the toc.yml.

- Cover
- Chapter-One
- Chapter-Two

Setting the reading order of the figures

b-ber creates figures pages during the build process. Each figure directive it encounters will be added to a list of illustrations. You can set the order of the list of illustrations by adding the figures-titlepage property to the toc.yml.

- Cover
- Chapter-One
- Chapter-Two
- figures-titlepage
- Colophon

It is not possible to change the order of the figures as they appear in the figures section. b-ber guarantees that they will be included in the same order as they are sequenced in the project's Markdown files.

Hiding content from the table of contents

b-ber creates an HTML table of contents toc.xhtml for each project during the build. To hide entries from the table of contents, add in_toc: false to that entry.

Note: This does not remove the file from the project. It only prevents it from being listed in the table of contents.

- Cover:
    in_toc: false # Will not appear in the table of contents
- Chapter-One
- Chapter-Two

Naming entries in the table of contents

Add a name to a chapter in the toc.xhtml by editing the front matter in the Markdown. No changes need to be made to the toc.yml.

Input

<!-- Chapter-one.md -->
---
title: Chapter One
---

Output

<!-- toc.xhtml -->
<nav id="toc" epub:type="toc">
  <h2>Table of Contents</h2>
  <ol>
    <li>
      <a href="text/Chapter-one.xhtml">Chapter One</a>
    </li>

Nesting entries

Nest chapters by wrapping them in a section in the toc.yml:

- part-1
- section:
    - chapter-1-1
    - chapter-1-2
- part-2
- section:
    - chapter-2-1
    - chapter-2-2

Chapters can be deeply nested:

- part-1
- section:
    - chapter-1-1
    - section:
        - chapter-1-1-1

EPUB: creating non-linear content

EPUB 3.0 allows for the inclusion of non-linear pages, which means they are hidden from the EPUB's table of contents. To accomplish this, assign linear: false to entries in the toc.yml. This does not remove the files from the project, it only hides them in the final output.

- chapter-1
- chapter-2:
    linear: false
- chapter-3

The in_toc and linear properties can also be combined.

- chapter-1
- chapter-2:
    linear: false
    in_toc: false
- chapter-3

Reader navigation

The b-ber Reader allows a user to navigate through the project by using keyboard forward and back arrows; by the previous and next spread (left and right-pointing arrows); and previous and next chapter (left and right-pointing chevrons).

The location in the project is cached as a user navigates and will be retained if the browser is closed. If a URL containing a slug parameter in the query string is included, the b-ber Reader will navigate to that chapter automatically, overriding any saved position. A chapter's slug parameter will be the title of the chapter as declared in that chapter's YAML frontmatter, which is located in the chapter's markdown file.

<!-- chapter-one.md -->

---
title: Chapter One
---

# Chapter One Title

In the previous example, the URL to take a user directly to "Chapter One" would appear as follows:

http://mysite.com?slug=chapter-one