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 |
| 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:
- Apache Cordova
- Android Studio for Android apps
- X-Code for Apple apps
- 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.
Windows
See these detailed guides on setting up a Windows machine:
- installing Jekyll on Windows (including Chocolatey, Ruby, and Bundler)
- installing the remaining Electric Book dependencies.
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.