/jekyll-epub

Create an eBook (epub) of your Jekyll blog

Primary LanguageRubyMIT LicenseMIT

jekyll-epub ↑

Create an eBook (epub) of your Jekyll blog

How To ↑

Create your blog ;) ↑

First, you need to create your own Jekyll Blog ;) Please, refer to the Jekyll documentation.

Configuration ↑

Then, you must add a configuration file : _epub.yml. This file is pretty similar to the Jekyll configuration file (_config.yml) except that’s you must add in some specifics entries. This entries are in the mapping epub:

_epub.yml :

epub:
  name: "My Jekyll Blog"
  lang: en
  identifier: my_blog.example.com-123456

Note that’s in the file, you can also use all the Jekyll configuration options. However, it is prudent not to change the permalink option, or you may spend a lot of time to set the proper access to resources (images, CSS, …). You have been warned;)

Here is the list of options :

  • name: String : The name of your book. This is a mandatory option.

  • title: String : The title of your book. This is a mandatory option.

  • identifier: String : A unique identifier for your book. If you have one, you can use an ISBN. If not given, Jekyll-epub will generate an UUID for you.

  • subject: String : The subject of the book.

  • description: String : An abstract of your book.

  • relation: String :

  • creator: String : The identity of the creator of the book.

  • contributor: String : The identity of the contributor of the book.

  • publisher: String : The identity of the publisher.

  • date: Date : You really want to know ;)

  • rights: String : The copyright of your book.

  • type: String : The type of the book (I mean the kind)

  • format: String : Some informations about the book format (The physical format)

  • source: String : Information about the source of the book.

  • coverage: String : Provides information on the spatial and/or time relevance of the book.

  • cover-image: String : The image to use for the cover of the book (i use a 540 × 648 pixels image)

  • pages-order: [page | post] : A list of pages and/or posts you want to order at the begenning of the book. If you don’t specify any order, Jekyll-epub will generate the book with the posts first (from the older to the newer), then the pages.

Layout ↑

If you want to use a special layout for your book, you can use the epub: mapping in the header of your pages, posts, layouts. This mapping is similar to the layout: mapping except that’s it is specific for the epub generation. In this example :

---
epub: my_ebook
layout: post
---
<p>This is the content of my post...</p>

When we generate the epub, Jekyll-epub will use the layout my_ebook.

Liquid extension ↑

You can also use two Liquid extensions :

{% epub %}
... This will only be display in the epub ...
{% endepub %}

{% noepub %}
... This will not be display in the epub ...
{% endnoepub %}

Since I have add those two extensions, if you want to use them, you also need to use one of the two following solution

Use jekyll_epub ↑

  1. Run jekyll_epub instead of jekyll to generate you site and eBook.

Otherwise, you will not be able to generate your (web) site.

See jekyll_epub --help for more information

Use Rack tasks ↑

  1. Create a Rakefile in your root’s Jekyll blog directory

  2. Add the following code in your Rakefile

require 'jekyll/epub/tasks'
Jekyll::Epub::Tasks do
  web :serve_port, 4000
  epub :destination, "_epub"
end

Use rake epub to generate the epub, use rake site to generate the website, use rake serve to serve the website.

Note on Patches/Pull Requests ↑

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright ↑

Copyright © 2010 Gregoire Lejeune. See LICENSE for details.