Setting up the Electric Book toolset on OSX

electric-book-tools-setup-osx.md

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.

https://jekyllrb.com/docs/installation/macos/

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 ryanwinchester.ca/posts/installing-homebrew-without-xcode. Essentially:

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

   xcode-select --install

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

   $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Ruby. We recommend Ruby version 2.7.3, because (at the time of writing) Jekyll requires a dependency that isn't in Ruby 3.0. This will install Ruby 2.7.3:

   brew install ruby@2.7

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

   If you do add to your PATH like this, close and reopen your Terminal. This will refresh your PATH with its new information.

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 princexml.com/doc/installing 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 phantomjs.org. 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 with homebrew: brew install node.

       (Alternatively, it can be better, but a little trickier, to install nvm and use that to install Node.)

    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.