Publishing Simple Books With Jekyll

2019-06-20

When thinking about writing, designing and ultimately publishing an ebook, most people don’t think of using a static site generator. Having products like Amazon Publishing, LaTeX or even Microsoft Word available, why should you use Jekyll?

Two reasons:

I know these same arguments could be made towards the other options mentioned above, but I’m biased towards Jekyll since I love the simplicity of HTML and CSS. Hopefully, after reading this post, you will feel the same as well!

No developer skills needed

You won’t need any hardcore development skills or in-depth knowledge of Jekyll to get the most out of this publishing technique. The theme (Jekyll Book Theme) will allow you to focus on your book’s content rather than wrestling with typography and page layouts. A basic command line script will perform all the heavy lifting for us at the end.

What are we creating?

You can see the demo of the online and PDF versions of the book below:

So without wasting anymore time, let’s get started!

Table of Contents

  1. Setup Jekyll
  2. Using the “Book” Jekyll Theme
  3. Writing Chapters
  4. HTML to PDF
  5. Closing Thoughts

1. Setup Jekyll

Before we can really do anything else, you will need to install and setup Jekyll. The best way to do so is by following the instructions on the official Jekyll website:

Run through the simple step-by-step installation instructions based on your operating system.

Basic requirements

2. Using the "Book" template

The example we will be referencing in this post is the open source Jekyll theme called “Jekyll Book Theme”. This theme as been designed and optimized for publishing ebooks with Jekyll.

Simply following the instructions on the main README page of the jekyll-book-theme repo.

Important: Take the time to edit the title, and author properties in the _config.yml file in the root directory. Make sure these reflect your own book’s content.

That’s it. Now let’s tell Jekyll how we want it to format our chapters.

3. Working with chapter collections

By default, Jekyll will look for latest posts in the _post directory. This is useful for blogs and basic static websites - but not for us. We want chapters.

Using custom collections

Thankfully, Jekyll is flexible and allows us to set our own custom “collections”. Collections are ways to group related content together for easier use dynamically. Our plan is to setup a collection that will house our chapter markdown files in numeric order. You can see this in the “book” template top level directory. It should look like the following:

But the template already has this setup

By default the Jekyll Book Theme template has this chapters collection implemented and working as intended. The reason I broke it down step-by-step is so that you can have some better understanding about what is happening “under the hood”.

Teach a person to fish and all that jazz.

Now all you need to do is break your chapters down into their own numbered markdown files inside _chapters.

4. HTML to PDF

Publishing with Jekyll

Before you can convert your digital book “website”, you need to install the wkhtmltopdf package. Download and follow the instructions below:

Command line conversion

In your terminal, navigate inside the _site folder of your jekyll build and then run the following command:

for f in *.html; do wkhtmltopdf -g -s Letter --no-background "$f" "${f/_*_/_}.pdf";done

Shortly after you should have a generated PDF file inside the _site folder - most likely named index.html.pdf. That’s it! Enjoy your fully formatted PDF version of your book!

5. Closing Thoughts

There are a good amount of pros and cons to this approach of “publishing” PDF versions of your book. Since I’m a sucker for good and bad bullet lists, let’s do just that:

The Good

The Bad

In the end, using something like LaTeX would certainly grant the user more flexibility in design and layout of the final “print” PDF product - but I’m a sucker for using Jekyll when I can.

Please let me know if you decide to use this method and end up publishing your own book 😀 I would love to check it out!