Building Stacks

The following is a guide to building and running Stacks locally. You’ll need to be able to build Stacks to contribute to our documentation or add new classes to our CSS library.

Install a full Ruby development environment

macOS

You’ll need a full Ruby development environment in order to run our static site generator. Let’s start by opening our Terminal app and installing a few things.

  1. Install Xcode. You can download it directly, or install via the Mac App Store.
  2. Install Xcode’s command line tools xcode-select --install
  3. Accept the Xcode license. sudo xcodebuild -license accept
  4. To Install a fresh version of Ruby, we’ll use Homebrew. Install it by running /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  5. Now you can use Homebrew to install Ruby brew install ruby
  6. Now’s a good time to quit your Terminal and relaunch it. This will make sure your session is aware of the new dependencies we’ve installed. Don’t just close the window, quit the whole app.

Windows

Download and install a Ruby+Devkit version from RubyInstaller Downloads. You’ll want to restart your computer before moving on.

Clone the repo

There are two common ways to clone a repo:

  • Use the command line: git clone https://github.com/StackExchange/Stacks.git
  • Use GitHub’s desktop app.
    1. Download and install GitHub Desktop.
    2. Login with your GitHub credentials.
    3. Clone the Stacks repo.

Get Node and NPM installed

We use a bunch of NPM dependencies to process and package up Stacks for delivery. You’ll need to install them.

  1. Install Node & NPM
  2. Open the Stacks repo in a Terminal window.
  3. Install the NPM dependencies. npm install

Install Bundler and Jekyll

We use Jekyll to generate our site. We use Bundler to install Jekyll and its dependencies.

  1. Switch to docs within the Stacks directory. cd docs
  2. Install Bundler and Jekyll gem install jekyll bundler. Depending on your environment, you may need to type your machine’s password a few times during this process.
  3. Install the Bundle bundle install

Running Stacks

That should do it for all our dependencies. You’re now able to run Stacks. 🎉

  1. From the top level of the Stacks repo, run our main script npm start
  2. Visit your local copy of Stacks at http://127.0.0.1:4000/

Getting Help

Installing dependencies can be frustrating, and we’re here to help. If you’re stuck, the Stacks team is always available in #stacks. If that doesn’t work, try opening an issue.