Epub output

Run the script

Run the output script for your OS and choose the epub option.


To embed fonts in an epub:

  1. add the font files to _epub/fonts;
  2. list the font files in _data/settings.yml at epub-fonts.


For guidance on adding Javascript to epubs, add the scripts to _epub/js. See the Javascript chapter for more detail.


If you want the output script to run EpubCheck (recommended), download it from the IDPF.

On Windows, extract the zip file and save the contents somewhere easy to find, like C:\EpubCheck\. Then add that folder to your PATH.

On Mac or Linux, extract the zip file and save the contents somewhere sensible like /usr/local/bin. The output script will ask for the path to the EpubCheck .jar file.

How epubs are generated

This is technical background on how we generate Electric Book epubs. It’s a two-step process.

  1. In Jekyll, using an epub config file (_configs/_config.epub.yml), we generate:

    1. the books, with each translation in a subfolder. Each book and translation has a package.opf file.
    2. an epub folder (as a Jekyll collection) containing a boilerplate META-INF folder, mimetype file, and mathjax folder; and optional js and fonts folders.
  2. In our output script:

    1. We copy the relevant book or translation folders from _site/book (or whatever folder book has been renamed to) into _site/epub. We retain the subdirectory structure of translations, except for the package.opf, which goes to the root of epub.
    2. We zip the contents of epub to _output/book.zip (where book may be a renamed book folder), and change the file extension to .epub

The output script does a lot of work. It asks the user some questions, it has to check for the existence of files (e.g. styles in a translation, which are optional), and it removes the mathjax folder from epub if mathjax is not included.


	This will find the videowrapper and store the URL of the embedded video in memory.

*	Replace with

	<a href="\2" class="button">Watch</a>

	This will replace the entire wrapper with a link to the same iframe URL it memorised (at `\2`). Replace `Watch` with whatever phrase you want to be the clickable text. 1.  If your book includes endnotes (kramdown footnotes), replace `fnref:` with `fnref-` and `fn:` with `fn-`. ( Background: If you have a colon in any element ID – for instance if you've used [kramdown's footnote syntax](http://kramdown.gettalong.org/quickref.html#footnotes) – EpubCheck will return an 'invalid NCName' error. You need to replace those colons with another character. If your invalid IDs follow a set pattern (as kramdown's footnote references do), you can replace-all quickly.) 1.	**Check your epub's metadata** using Sigil's Metadata Editor, and edit if necessary. Include at least:
*	title: subtitle
*	author
*	date of creation
*	publisher
*	ISBN (or other identifier like a [UUID](https://www.uuidgenerator.net/))
*	Relation ISBN (if any; we use the print ISBN as a parent ISBN) 1.	**Add file semantics** (right click the file name in Sigil for the semantics context menu) to:
*	key HTML files
*	the cover JPG. 1.	{:#adding-the-epub-toc}**Generate the epub's table of contents** (Tools > Table Of Contents…). This TOC is generated only from the headings (`h1` to `h6`) in the text. So it does not include the cover, which has no heading, or any other files without a heading (e.g. sometimes the copyright page). If you need to add a cover to the TOC:
1. Go to Tools > Table Of Contents > Edit Table Of Contents… 
2. Click on the first entry in the TOC list.
3. Click 'Add Above'.
4. Click 'Select Target' and select the cover HTML file (usually `0-0-cover.html`).
5. In the blank space under 'TOC Entry', double-click and type 'Cover'.
6. Click Okay.
7. Use the same process for adding any other files you need to add to the TOC. 1.	If fonts are important (you've either embedded fonts or the difference between serif and sans-serif is semantically significant), add iBooks XML. ([See below for detail](#adding-ibooks-display-options-file).) 1.	{:#validate-the-epub}Validate the epub in Sigil and fix any validation errors. Sigil let's some things past that EpubCheck flags, so also validate with EpubCheck directly. You can use:
*	the [IDPF's online version of EpubCheck](http://validator.idpf.org/)
*	[epubcheck](https://github.com/IDPF/epubcheck/wiki/Running) installed locally, and run from the command line; or
*	[pagina EPUB-Checker](http://www.pagina-online.de/produkte/epub-checker/).

Tip: If you get validation errors about images, check that your paths to images are correct and case-sensitive. For instance, Sigil needs images to be in Images not images.

For general guidance on creating epubs with Sigil, check out EBW’s training material and the Sigil user guide.

Splitting large files

If you have very large text files that, in the epub output, you’d like to split up into separate HTML files, Sigil can help. Using this tag in HTML, you can mark where Sigil must split your HTML file(s):

<hr class="sigil_split_marker" />

To create that in markdown, use a three-asterisk divider with a sigil_split_marker class, like this:


Also, remember to hide those markers in print output (and web and elsewhere as needed) with this in your CSS:

.sigil_split_marker {
	display: none;

Then, when you’re assembling the epub in Sigil, just run Edit > Split At Markers.

Sigil will then split the HTML file into separate HTML files at the markers, and remove the <hr> element.

A common use case for this is books with end-of-book endnotes. To create end-of-book endnotes using kramdown footnotes you must put all content with endnotes in one markdown (and therefore HTML) file. This file is too large for sensible epub use, so splitting is important. Sigil is smart enough to update your internal links when you run ‘Split At Markers’.

NB: Before running Split At Markers: save, close, and reopen your epub. At least till Sigil 0.9.3, there is an issue with updating internal links when using Split At Markers. In order for internal links to update correctly, Sigil must first have rewritten all link paths to HTML files according to its ../Text/ folder structure (e.g. the links to chapters in a Table of Contents file). Sigil only rewrites all these paths when an epub file is opened. So to make sure links are udpated when running Split At Markers, you need to save, close, and reopen the epub first. This may be fixed from Sigil 0.9.5.

Mobi conversion

These days, you should not need to create a mobi file for Amazon. It’s better to upload an epub and let Amazon convert it.

If you really do need a mobi file, we recommend putting your EPUB into the Kindle Previewer, which automatically converts to mobi using Kindlegen and saves the mobi file to a folder beside your epub.

If Previewer cannot convert the epub, we’ve found that adding it to Calibre first, then (without converting) give Calibre’s version to Kindle Previewer. Calibre gives you greater control over specific ebook conversions, but we’ve found Kindle Previewer converts some CSS better (e.g. floats and borders).

If you need to dig into a mobi file’s code to troubleshoot, try the KindleUnpack plugin for Calibre.

EPUB3 conversion

To convert an EPUB2 to EPUB3 in Sigil, use Kevin Hendricks’ EPUB-itizer plugin.

Note that EPUB3 prefers all files to have .xhtml filename extensions, while Jekyll uses .html. So, before you run the EPUB3-itizer:

  1. In Sigil’s BookBrowser window select all .html files
  2. Right click on your selection and select Rename
  3. In the “Rename Files Starting At” dialog, remove everything and replace it with .xhtml and click “OK”.

When adding file semantics, we have found that setting cover.jpg to ‘Cover image’ (i.e. adding <meta content="cover.jpg" name="cover" /> to content.opf) causes KindleGen to crash when converting to Amazon formats. So you may want to avoid this setting for the cover image file.

Adding iBooks display-options file

If you need to add the com.apple.ibooks.display-options.xml file to your epub for iBooks display options, you can use the AddiBooksXML plugin in Sigil.

A very basic display-options file contains this XML:

<?xml version="1.0" encoding="UTF-8"?>
    <platform name="*">
        <option name="specified-fonts">true</option>
        <option name="interactive">false</option>
        <option name="fixed-layout">false</option>
        <option name="open-to-spread">false</option>
        <option name="orientation-lock">none</option>

The file should be in the epub’s META-INF folder, which Sigil does not let you edit by default, hence the need for the plugin.

To install the plugin:

To use the plugin: