A Ruby script/gem to create EPUB books from Jekyll posts and pages using Pandoc
A Ruby script/gem to create EPUB books from Jekyll posts and
pages using Pandoc.
Lincoln A. Mullen | [email protected] | http://lincolnmullen.com
You can install jekyll-ebook using RubyGems:
gem install jekyll-ebook
This gem depends on pandoc-ruby, which should be installed for you
automatically when you install jekyll-ebook. If not:
gem install pandoc-ruby
If you don’t have it installed already you will need to have the
Pandoc executable in your path. See the Pandoc documentation for
instructions.
You can run the script from the command line. It takes as arguments, the
filenames of YAML manifest files, one per e-book. To run the script:
jekyll-ebook manifest.yml
The manifest is a YAML file that sets some options tells the script
which posts and pages should be part of the EPUB. (If you’re using
Jekyll, you’re already familiar with YAML.)
The following fields should be in the manifest.
title: The Journal of Southern Religion
author: Volume 14
date: October 2012
The title, author, and date of your EPUB are set in the manifest.
epub-filename: out.epub
epub-cover-image: cover.jpg
epub-stylesheet: stylesheet.css
epub-metadata: metadata.xml
epub-dir: /Users/username/project/
The epub-filename is the path to the EPUB file that the script will
output. (NB: For now, if the directories in the path do not exist, the
script will fail.)
Besides the body content, a proper, well-formatted EPUB requires a
stylesheet, a cover image, and a rights file. This script uses
pandoc-ruby to call for three files. epub-cover-image,
epub-stylesheet, and epub-metadata are paths to an image, a CSS
file, and an XML file respectively. These paths are relative to
epub-dir, so that you can specify the directory that holds these files
one time. To see what belongs in each of those files, see John
MacFarlane’s guide to creating an e-book with Pandoc.
header-items:
- title
- author
- author-note
- citation
The YAML metadata for your posts and pages contains information that you
probably don’t want in your e-book, such as the categories or permalink.
Your YAML metadata might also include custom fields that you do want to
include. In my case, I often have a field book-reviewed that should be
included.
Your manifest should specify an array of header-items that you want to
include in the order that you want to include them. The title is
always included as the first item, whether or not you specify it. The
other items are included only if they exist for a given post or page.
The items are each wrapped in a <p> tag with a class named after the
metadata item (e.g., <p class='book-reviewed'>), so you can change the
styles with your stylesheet.
content-dir: ./
contents:
- section-title: Articles
files:
- article1.markdown
- article2.markdown
- section-title: Reviews
files:
- review.markdown
This script loops through the files you want included in the EPUB in the
order you specify, formatting them properly.
The content-dir option sets the path to your Jekyll posts and pages.
You might set content-dir to the path to your _posts directory.
The contents option lists the files you want to include, organized by
section. The section-titles will create header pages separating the
main parts of your book. The files arrays list paths relative to
indir that should be included. These are your Jekyll posts or pages.
You can have as many sections and included files as you wish.
This code is alpha. If you find bugs or ways to improve the code, please
let me know in the GitHub issues tracker or by e-mail.
I wrote this script for the Journal of Southern Religion, which
runs on Jekyll. There may be items in this script which are specific
to my intended purpose, but I have tried make the script generally
useful.