Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Setting up the Electric Book toolset on OSX

Setting up the EBW tools on Mac OSX

These steps have worked for us on several machines. Every machine is a bit different, so your mileage may vary.

On Windows? I've written up guidance for installing on Windows here.

  1. Install Homebrew (without XCode -- you do not need to install XCode!). This is done in two steps from the Terminal. See Essentially:

    1. Install XCode developer tools (lets Homebrew work):

    xcode-select --install

    1. Install Homebrew (lets you install things easily):

    ruby -e "$(curl -fsSL"

    On some systems, this doesn't work and you need to include the full path to Ruby:

    /usr/bin/ruby -e "$(curl -fsSL"

  2. Install the latest Ruby:

    brew install ruby

    To check whether that worked, enter ruby --version. If it doesn't list a recent version of Ruby (2.4 or later), you may have to add the new version to your PATH.

  3. Install Jekyll:

    gem install jekyll

  4. Install Bundler:

    gem install bundler

    To check that Bundler is installed, enter:

    bundle -v

    If it isn't, you may need to add the path to your gems to your PATH. To do this, first run gem environment to get the directory of the executable directory, which may look like /usr/local/lib/ruby/gems/2.5.0/bin. To add that to your path, you add export PATH= /usr/local/lib/ruby/gems/2.5.0/bin:$PATH to your ~/.bash_profile file. (This discussion has some more detail.)

  5. Download and install PrinceXML. See for instructions. Note that this is proprietary software (the only proprietary tool we use). You can try the trial version for free; it adds a watermark to your first page.

  6. [Note: this step is only necessary for Electric Book template v.0.15 and earlier. Phantom is not required from v0.16.0] Install PhantomJS. This is necessary for building search indexes for websites. (And, in older repos to Electric Book template version 0.12, for creating PDFs that contain maths.) Download from Extract the zip archive and copy the phantomjs executable file in bin to your machine's /usr/local/bin folder.

  7. Install Pandoc if you're going to export to Word:

    brew install pandoc

  8. Install Git for version control. If you're new to Git, try GitHub Desktop. (Git isn't easy to understand at first, but it's worth the effort.)

  9. Install a good text/code editor. I like VS Code and Sublime Text 3. Brackets is also good. (Atom is lovely, but has a markdown bug that may also affect Brackets and VS Code.)

  10. Install Gulp and Graphicsmagick. We use these to create multi-format images. To do this:

    1. Install Node.js.

    2. Install gulp: npm install --global gulp-cli

    3. Install GraphicsMagick: brew install graphicsmagick

      Note: Once upon a time, Homebrew did not include Little CMS in its graphicsmagick recipe, and we had to install GraphicsMagisk with brew install graphicsmagick --with-little-cms2. If you had already installed GraphicsMagick but without specifying --with-little-cms2, you needed to brew uninstall graphicsmagick first. Little CMS is required for managing colour profiles during image conversions. Homebrew currently installs Little CMS by default.

App dependencies

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

The Electric Book scripts will use these in the background, and for some build steps you'll have to use these directly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment