Setting up your computer

If you want to edit and output books on your own computer (as opposed to using a hosted, online service like the Electric Book Manager), you need to get it set up first.

The Electric Book workflow is like a toolkit: it uses a range of great open-source projects. So setting it up involves installing this software. We also use one proprietary, commercial application called PrinceXML, which is for creating PDFs. (If you’re only making ebooks, websites and apps, you don’t need Prince.)

We recommend installing this software in this order (since some of these applications depend on others):

Software Reason
A Ruby version manager (e.g. Homebrew on Mac or Chocolatey for Windows) Ensures you’re using the right version of Ruby
Ruby 2.4 or later The language that Jekyll runs in
Jekyll Builds finished HTML from your content and the Electric Book template
Bundler Manages other Ruby applications (‘gems’) that Jekyll depends on
PrinceXML Converts Jekyll’s HTML into PDF
PhantomJS Used for rendering maths for PDF and building website search indexes
Pandoc Used for converting books to MS Word
Git (or a Git desktop app like GitHub Desktop) Used for version control
A code editor (e.g. Sublime Text, VS Code, Brackets) The best way to edit markdown and other content and style files
Node.js Required to run Gulp
Gulp Used for processing image files in bulk
Graphicsmagick Used for multi-format image conversions

If you also want to create apps, you will need to install:

  1. Apache Cordova
  2. Android Studio for Android apps
  3. X-Code for Apple apps
  4. Visual Studio for Windows apps

Detailed guides

Each of the tools listed above have their own installation guides. Nonetheless, sometimes you need extra guidance for the tricky bits or options specific to the Electric Book workflow.

Mac

For a detailed guide on installing all dependencies on a Mac, see this guide by Arthur Attwell.

Windows

For a detailed guide on installing Chocolatey, Ruby, Jekyll and Bundler on Windows, see this guide by Arthur Attwell.

Linux

We don’t have a detailed guide for setting up on Linux yet. Ubuntu users who are familiar with shell scripts will find this script useful. It installs all the dependencies in one go. Don’t run it as-is unless you know what you’re doing. It may be better to read it as a guide to the commands you might run to install each Electric Book dependency in turn.

Suggestions

If you know of other good guides to setting up these applications, especially for Ubuntu Linux, please let us know. We have successfully installed all of these tools on Ubuntu, using each project’s own installation guides and various online fora.

You can add suggestions on the Electric Book issues tracker.