SteGriff

Blog

Next & Previous

Set up Slate documentation generator on Windows in 2019

Slate in action

Slate is a documentation site generator which runs on Ruby via the Middleman site generator, with a JavaScript frontend. It doesn’t officially support Windows but it is pretty easy to get it up and running (when I wrote this!)

At first I had a problem with RubyGems, which complained that my ruby version needed to be <2.5, but I fixed this by deleting Gemfile.lock and re-running bundle install.

It’s important to run bundle install once and let it fail before you delete Gemfile.lock.

Steps

  1. Install Ruby using Ruby Installer. I don’t think you need the devkit but it comes in handy if you’re running other ruby things in the future. x64 is fine, I have ruby 2.5.3p105 [x64-mingw32] but I installed it a while ago! Make sure you tick the box to add Ruby to your PATH!
  2. Fork the original Slate repo on GitHub and clone your new fork of slate down to your PC (git clone https://github.com/username/slate.git)
  3. Install bundler: Open a good terminal (I normally use Git Bash) and run gem install bundler
    • You might even want to match your bundler version to theirs by looking at the bottom of Gemfile.lock and specifying a version like this: gem install bundler --version 1.15.4
  4. In a terminal in your slate directory, run bundle install and allow it to fail!
  5. After it fails, delete Gemfile.lock
  6. Run bundle install again and it should work now
  7. Run bundle exec middleman
  8. Go to http://localhost:4567

Running middleman

That should bring up the default Slate docs site. Did it work?

Node.js

If you get this error:

Current ExecJS runtime does’t support ES5. Please install node.js.

Then you should install Node.js from nodejs.org. After installing it, end your middleman process (Ctrl+C, y), close the terminal, open a new one, and re-run bundle exec middleman.

Edit 2019-07-03

I’ve amended this guide because on my first run it worked thanks to a fortunate series of events. The first time you bundle install you will get an error like this:

In Gemfile:
  middleman was resolved to 4.2.1, which depends on
    middleman-core was resolved to 4.2.1, which depends on
      listen was resolved to 3.0.8, which depends on
        rb-inotify was resolved to 0.9.8, which depends on
          ffi

…and only then can you fix the process by deleting Gemfile.lock and re-running the command.