eleventypub

This is an 11ty project template, configured to build an EPUB 3 fileset. It includes options to validate and run accessibility checks.

Gentle is a good tool for audio syncs $ git clone https://github.com/marisademeglio/eleventypub.git

Quickstart

First, install 11ty.

Then, clone this repo and start editing:

$ git clone https://github.com/marisademeglio/eleventypub.git
$ cd eleventypub
$ npm install

Go to src/pages. Edit the pages there or make your own, following the examples.

Go to src/cover.md and make a cover page.

In the terminal:

$ npm run build

Your EPUB fileset is in build/epub.

To build, validate, save, and run accessibility checks, all from one command, do what it says under Configure Tools, and run:

$ npm run all

This command builds, validates with EPUBCheck, runs Ace, and saves an .epub file, and an Ace report.

Configure Tools

These third party tools enable saving as .epub, validating, and performing accessibility checks.

• Download and unzip EPUBCheck
• Install Ace by DAISY.
• Install npm-run-all

After you've unzipped EPUBCheck, set the path to your EPUBCheck jar in package.json.

Conventions

This part of the README assumes you are familiar with 11ty. It discusses project structure and options.

You have as much freedom as you have with 11ty to mix and match templates and options. It's up to you to make sure the files pass EPUB 3 validation (configure some free tools so you can run the validation step).

This project uses the following conventions:

pages/

Chapter files live in this directory.

In pages.json, it says, among other things:

`tags: pages`

Don't change this.

index.md

The package document. Don't touch this file.

toc.md

Table of contents. The filename isn't special, just reference it correctly from pub.json and use a TOC template (in this case, toc.njk).

cover.md

Cover. The filename isn't special, just reference it correctly from pub.json.

_data/

This data ends up in the package document.

• metadata.json: as many dc terms, properties, and links as you want.
• pub.json: toc, cover, and readingOrder(optional)

resources/

This directory is for fonts, CSS, images, etc; basically, anything you want listed in the manifest and copied over.

_includes

These are all the layout templates, which create XHTML, OPF, and navigation documents. You can edit and replace these with your own, using any markup syntax supported by 11ty. If you use your own templates, it's up to you to make sure you're producing valid EPUB 3 output.

Scripts

$ npm run [something from the list below]

• build: create the EPUB fileset
• epubcheck: run EPUBCheck on the output
• save: run EPUBCheck and if valid, save an EPUB file
• ace: run the Ace accessibility checker. The report will be in build/report
• pretty: run an XML-prettifier on package.opf and all xhtml files.
• all: build, prettify, validate+save, and check accessibility

FAQ

Can I use other formats for my templates?

Yes absolutely! You can do whatever's possible with 11ty, which is a lot.

The templates in this project are nunjucks and markdown. The configuration I use for markdown includes having it output XHTML. Then, in the postbuild step, all html files are renamed to xhtml. Even so, there are surely still ways to produce EPUB-invalid XHTML with this setup.

So, whatever you try, it's up to you to make sure that your output is valid. Be sure to configure your tools so you can run EPUBCheck.

What are the TOC options?

Point to your TOC file from pub.json. Point to the final output, e.g. toc/index.html, not the input.

In this basic example, the TOC is the file generated by src/toc.md. It is set to autogenerate, so the file is empty after the front matter data.

If I wanted to specify a TOC manually, I would write something like:

---
layout: toc.njk
title: Table of contents
EPUBRoot: ".."
auto: false
---
1. [Introduction]({{EPUBRoot}}/pages/intro/index.html)
1. [Chapter 1]({{EPUBRoot}}/pages/chapter1/index.html)
1. [The end]({{EPUBRoot}}/pages/end/index.html)

auto: true the TOC will be autogenerated. Each chapter file will get an entry with its title (I never said we were fancy).

auto: false: you provide everything that's going to go between <nav> and </nav> in your TOC file. It's up to you to make sure these contents are EPUB 3 compliant (e.g. a valid XHTML ordered list).

If you're providing your own TOC, triple-check the file references to make sure the relative path is correct (use EPUBRoot to help). Also, make sure you point to xhtml files, as that's what they'll be in the end, as a result of our postbuild step.

What are the reading order options?

You can add a readingOrder in pub.json. It's an array of fileSlugs of the files in order. If readingOrder is not specified, a reading order gets generated automatically in alphabetical order based on what's in pages/.

All file slugs in a custom reading order have to be for files in pages/.

Future

There's lots of room for expansion. Some ideas could be:

• Fine tune TOC autogeneration with some options
• Have more TOC templates, for example something with a pagelist.
• Add media overlays (based on what input I'm not sure, maybe some kind of timestamp list)
• more robust build process
  • the XHTML-ification is spread out in a few different places)
  • no control over where files get output (get 11ty's default behavior, e.g. for chapter1.md, to output chapter1/index.html)