Install Software

Visual Studio Code (VS Code) has a tremendous number of extensions that can be added to enhance it’s functionality. We recommend Rainbow CSV, which will help you better read the CSVs within CollectionBuilder, and Code Spell Checker, which will check your spelling.

VS Code is incredibly customizable via its settings as well.
To configure the editor, click the gear icon in the bottom left corner of the VSCode window and choose Settings. The searchable Settings pane has information about all the configuration options. When you first install VS Code, the default settings can be distracting, so don’t be afraid to turn things off!

• Windows:
  • Install Git for Windows using the default options, except when setup asks you to choose the default editor used by Git, select “Use the Nano editor by default”. This will give you Git, Git Bash, and Git GUI. Git Bash is a terminal that lets you use UNIX style commands and utilities on Windows, and will be used as your default terminal when working with Jekyll.
• Mac:
  • Mac systems will require the “Xcode Command Line Tools” installed, so open a terminal (to find your terminal search for “terminal” in your Spotlight), type in the command xcode-select --install, and follow the prompts. After the install finishes, try typing git --version. If you want a newer version of Git, download the official Mac git installer.
• Linux:
  • Install from your distribution’s software center or package manager (for Ubuntu sudo apt install git).

Once Git is installed, we need to configure your information, so that it can connect with your GitHub account. Since Git is a command line application, we will need to open a terminal to give it commands. On Windows, search for “Git Bash.” On Mac and Linux, search for “terminal.” Once you have a terminal open, we will need to give it two commands.

First, set your user name so that it matches your GitHub user name:

git config --global user.name "User Name"

Second, set your email so that it matches your GitHub account’s email:

git config --global user.email "myemail@gmail.com"

Optionally, set your default command line text editor for use with git. This editor may pop up in your terminal during some command line git operations that require a message (it is not your normal code editor such as VS Code). By default it is set to Vim, which can be very confusing if unexpected. For ease of use, we generally suggest using Nano editor:

git config --global core.editor "nano -w"

If you are new to using Git and GitHub, we also recommend you install GitHub Desktop using the default options. This will help you visualize and implement some of the git processes that can seem non-intuitive.

GitHub Desktop is available on Windows and Mac only, however, there are a variety of other GUI app for working with Git available, including “git-gui” that is built in to every default Git install. Many users will find they complete most Git commands using integrations built into their text editors such as VS Code or Atom instead.

Use RubyInstaller for Windows.

• First, download the suggested stable version “WITH DEVKIT” (as of this writing, Ruby+Devkit 2.7.X (x64)) and double click to install. Use the install defaults, but make sure “Add Ruby executables to your PATH” is checked. On the final step, ensure the box to start the MSYS2 DevKit is checked.

• Second, the installer will automatically open a terminal window with options to install MSYS2 DevKit components. Choose option 3, “MSYS2 and MINGW development toolchain”, or simply press ENTER to install all the necessary dependencies. The installer will proceed through a bunch of steps outputting a bunch of text in the terminal window – eventually, this will conclude and you should see a message with success in it. If the window doesn’t close, press Enter again or manually close it. (The installer can be restarted by typing ridk install into a command prompt)

• Having trouble? Need more detail? See How to Install Ruby on Windows for help.

Installing Ruby on Mac can be difficult, but don’t be deterred! If the method below doesn’t work for you check out How to Install Ruby on a Mac for more detail and other options.

OS X has a version of Ruby installed by default, but recommended practice is to set up a separate Ruby development environment. To do this, follow the instructions below, which outline the steps to install Ruby using rbenv.

Get the Xcode Command Line Tools First

• Ensure you have Xcode Command Line Tools, so that you can work with Ruby (and Git, etc.).
• To do this, open your terminal by clicking Command (⌘) + Spacebar, typing terminal into the spotlight box that appears, and pressing Enter.
• Type xcode-select --install into the terminal window and press Enter to start the installer. Note: this may take some time to install.

Use rbenv to Install Ruby

1. Install Homebrew
   • You’ll need to use Homebrew to install rbenv. To install Homebrew, follow these steps:
     • Open the Homebrew webpage in your browser.
     • Open your terminal by clicking Command (⌘) + Spacebar, typing terminal into the spotlight box that appears, and pressing Enter.
     • Once inside your terminal, copy the script in the box underneath “Install Homebrew” on the Homebrew webpage. Paste this script you just copied into the terminal prompt and press Enter.
     • You’ll then be prompted to press Enter once more to continue the install.
2. Install rbenv
   • Copy and paste the command brew install rbenv into your terminal prompt and press Enter. This installation might take a while.
   • Once rbenv has been installed, copy and paste rbenv init into the terminal prompt and press Enter.
   • Depending on whether you are using a zsh or bash shell, follow the appropriate instructions below to finish the rbenv installation.

# Load rbenv automatically by appending
# the following to ~/.zshrc:

eval "$(rbenv init -)"

Install Ruby

• Back in your terminal, install the latest version of ruby by copy/pasting or writing, rbenv install 2.7.3 and pressing Enter.

Note: 2.7.3 is the latest solid version as of this writing; if you are reading this past Fall 2020, you may want to check the “Stable Releases” section on the download Ruby page and install the latest stable version.

• Now let’s set that version as your global Ruby version by entering rbenv global 2.7.3 into the terminal prompt and pressing Enter.
• Finally, we’re going to rehash, just to be safe: copy and paste the command rbenv rehash into your prompt and pressing Enter.
• Now let’s see if that worked.
  • Quit your terminal by right clicking (Control + click) its icon in your applications menu, and selecting Quit from the options that appear.
  • Then reopen your terminal by clicking Command (⌘) + Spacebar, typing terminal into the spotlight box that appears, and pressing Enter.
  • Type ruby -v into the terminal prompt, and press Enter.
  • If your terminal indicates that you have Ruby 2.7.0 or higher installed, you’ve done it!

If this installation did not work, see our more detailed guide, How to Install Ruby on a Mac, check out the Jekyll install on mac docs, or try Googling any error message or other hindrance you encountered.

Ruby can be installed via most distro’s repositories or snap package, however, it is more up-to-date and best practice to use a version manager such as RVM or rbenv.

• First, ensure you have build tools Make and GCC installed (on Ubuntu get them with sudo apt install build-essential).
• Follow the instructions on RVM install or rbenv notes.
• For more information and other methods, see How to Install Ruby on Linux.