Updating the wiki

Table of contents

1. Getting Started
   1. Github
   2. Ruby and Jekyll
      1. Ruby
      2. Jekyll
   3. Clone the repo

---

All SNaP Lab members are expected to document their projects on this wiki. This tutorial is designed to get you started editing this site and contributing to its contents.

Getting Started

Github

First, you will need a GitHub account in order to be able to contribute; this website is automatically generated by a code repository on Github and is written primarily in markdown. If you haven’t already, go setup a GitHub account and ask Linden to invite you to the lab’s repository.

Ruby and Jekyll

For long term editing, the best solution is to clone this repository onto your own computer and edit it locally. Using a combination of Ruby and Jekyll, you can compile a local version of this site that will allow you to preview your edits quickly before they go live. Once you’re satisfied with your contributions, you will then submit a Pull Request on Github that merges your edits into the main repository. From there, your edits will be automagically incorporated into the online version of the site.

Ruby

First, install ruby on your local machine (see here for longer instructions). If you’re on Mac or Linux, the best way to do this is to use Homebrew. Once you have Homebrew installed, you will access to the command brew in your terminal. Next, use brew to install ruby, like so:

$ brew install ruby

Note, your computer might already have a system version of ruby installed (e.g., Mac OS does). This isn’t going to work for us. Ignore it. To ensure your newly installed version of ruby is ready to use, you will also need to edit your terminal profile. If you’re using a Mac with the newfangled Apple Silicon chips, do the following:

$ open -e ~/.zshrc

In the file that subsequently opens in TextEdit, add the following lines, then save and quit:

if [ -d "/opt/homebrew/opt/ruby/bin" ]; then
  export PATH=/opt/homebrew/opt/ruby/bin:$PATH
  export PATH=`gem environment gemdir`/bin:$PATH
fi

Now quit and reopen your terminal and you should be ready to use ruby, but let’s verify:

$ which ruby

This should return something like:

/opt/homebrew/opt/ruby/bin/ruby

If you get something like the above, you’re good to go!

Jekyll

Using ruby, install jekyll. Note, the command line function that invokes ruby is gem:

$ gem install --user-install bundler jekyll

Clone the repo

Now that you’ve got the tools you need, let’s clone the GitHub repo for this site!

$ cd ~/
$ git clone https://github.com/LindenParkesLab/snaplab.github.io.git

If you look in the repo directory, you will see a folder called docs/. This is where you will add to and edit the content of this wiki. Next, change into the repo directory and build the site. Basically, you’re going to tell jekyll to take all of the contents in the current directory and spin them up into a webpage, and ruby will serve it to on your local machine:

$ cd ~/snaplab.github.io
$ bundle exec jekyll serve

If you see something that ends with this:

Server address: http://127.0.0.1:4000/snaplab.github.io/
Server running... press ctrl-c to stop.

You’re in business! Just visit http://127.0.0.1:4000/snaplab.github.io/ in your web browser to view the local version of the SNaP Lab wiki!

You can now edit files locally in docs/, and whenever you save a file, the local web page will update automatically to reflect those changes! When you’re done, hit CTRL-C in your terminal to stop serving the site, and then submit your Pull Request to put them on the internet.

Look at you go.