Skip to content

Handbook Setup

Turn On Notifications

In order to make use of the Handbook it's important that you are able to receive notifications from GitLab. Here are instructions on how to configure this:

  1. Open Settings from your profile drop-down at the top right of GitLab
  2. Select Notifications from the User Settings menu on the left nav bar
  3. Confirm that the Notification email has your email address
  4. Set the Global notification level to Participate
  5. Confirm that all of the Groups and Projects on the lower section of the page are set to Global

This will configure GitLab to send a notification email on all tasks and changes for which you are a participant or @mentioned, and it should be your default setting. You may modify these settings to better suit your preferences (instructions are available in GitLab documentation), but it is your responsibility to stay aware of requests made of you through GitLab.

Screenshot illustrating the proper notification settings... GitLab Notification Settings

Set up a local copy

You can contribute entirely through the online process above. However, you may also wish to set up a local copy of the handbook. This will make it easier to preview your changes and also gives you access to a few other writing tools that make it more user friendly. There's a bit more complexity to this process, but this guide should get you going.

To set up a local version of this handbook, you will need at least the following set up on your machine:

  1. Git -- see these installation instructions
  2. A Markdown editor -- we recommend Typora for a simple visual experience or Atom if you want an environment integrated with git.
  3. A local copy of the repository (instructions below)

This setup will be sufficient to make changes to the documentation, and is user-friendly for non-developers. You'll be able to see and contribute the files within the documentation, but won't have the same UI as on the website. If you want that full experience, you please install MkDocs.

Setting up Git

You will need to set your credentials in git. This may be a bit daunting at first, so we'll step through it together. Instructions are here

Git setup for Mac

From your terminal, run the following:

  1. git config --global "John Doe"
  2. git config --global "[email protected]"

Local copy of repo

To create a remote copy of the repository, open your terminal interface and navigate do the directory where you want to store it. (Nolan suggests ~/Projects.) Then run git clone; this will create a handbook directory that has the latest copy of the project.

Make your first edit

To make your first edit:

  1. In your terminal, run git pull
  2. Open your markdown editor from the docs/ directory within the Handbook
  3. In your markdown editor, make a change and save it
  4. In your terminal run git add . or git add docs/
  5. In your terminal, run git commit -m "Make first contribution"1
  6. In your terminal, run git push

Run locally

If you want to run the handbook locally so you can see edits before committing, you also will need to set up your local environment to run mkdocs and other dependencies for the handbook. Setting up a local environment sometimes is easy and we'll outline the simple steps here. Unfortunately, complexities can sometimes arise based on other things in your environment; if this happens try Googling the error message and see if you can easily resolve it. If not, reach out for help!

The basics that you'll need are:

  1. Some installer -- we recommend Homebrew
  2. MkDocs -- try brew install mkdocs
  3. Mkdocs Material theme -- try pip install mkdocs-material
  4. Material Extensions -- try pip install mkdocs-material-extensions
  5. Click Here to access your local copy of the Handbook.

Note that in order to do this, you will need to know a bit about how to use the command line within the Terminal app (assuming you're using a Mac). Here's a quick primer.

Notes on updating / upgrading local environment

  1. Make sure to periodically update and upgrade brew: brew update && brew upgrade then brew cleanup
  2. Note that I first had to update all of my command line tools. (I don't remember the link to these instructions)
  3. In order to update brew, you may need to git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core fetch --unshallow, which grabs the latest list of tools. Then I ran brew upgrade. Based on the system's warning I also did brew link --overwrite [email protected]
  4. Update mkdocs: brew upgrade mkdocs failed, so I ran brew install mkdocs. This process also required brew link --overwrite mkdocs since there was a previous version.
  5. Install mkdocs-extensions by doing python3 -m pip install mkdocs-material

Updating local environment to run website

The website runs using Jekyll instead of MkDocs.

  1. Install rbenv: brew install rbenv. Use Homebrew to install rbenv, but use rbenv to do the rest of the install.
  2. Install Ruby: rbenv install 2.6.3 then rbenv global 2.6.3. Note that the website has dependencies that have not been updated in the latest version of Ruby; 2.6.3 is known to work.
  3. Install Jekyll: gem install bundler jekyll. Doing this required brew install openssl
  4. bundle install
  5. bundle exec jekyll serve
  6. Click Here to access your local copy of our website.

  1. This creates a 'commit' with a message. A commit is an individual change to a set of files. Your message should be a brief and concise description of a simple change you're making to the docs. Make the first word of your commit message a verb, and use present tense.