Using Slate Natively

This page is for installing and using Slate on the native OS, as opposed to using Vagrant or Docker.

Dependencies

Minimally, you will need the following:

• Ruby >= 2.6
• Bundler
• NodeJS
• Git

Please note, only Linux and macOS are officially supported at this time. While slate should work on Windows, it is unsupported.

See below for installation instructions for different OSes / distros.

Installing Dependencies on Linux

Install Ruby, NodeJS, and tools for compiling native ruby gems:

On Ubuntu 20.04+

sudo apt install ruby ruby-dev build-essential libffi-dev zlib1g-dev liblzma-dev nodejs patch

On Fedora 31+

sudo dnf install @development-tools redhat-rpm-config ruby ruby-devel libffi-devel zlib-devel xz-devel patch nodejs

Then, update RubyGems and install bundler:

sudo gem update --system
sudo gem install bundler

*Note

If you get the following error

ERROR: Your RubyGems was installed trough APT, and upgrading it through RubyGems itself is unsupported.

try the following commands instead:

sudo apt-get update -y
sudo apt-get install -y bundler

Installing Dependencies on macOS

First, install homebrew, then install xcode command line tools:

xcode-select --install

Agree to the Xcode license:

sudo xcodebuild -license

Install nodejs runtime:

brew install node

Update RubyGems and install bundler:

gem update --system
gem install bundler

Getting Set Up

1. Fork this repository on Github.
2. Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/slate.git
3. cd slate
4. Install ruby gems for slate:

# either run this to run locally
bundle install

Note: if the above fails on installing nokogiri and using macOS see here for some helpful tips on things that might help.

Running slate

You can run slate in two ways, either as a server process for development, or just build html files.

To do the first option, run:

bundle exec middleman server

and you should see your docs at http://localhost:4567. Whoa! That was fast!

The second option (building html files), run:

bundle exec middleman build

What Now?

The next step is to learn how to edit source/index.md to change the content of your docs. Once you're done, you might want to think about deploying your docs.