---
tags: BVCN
---

# Being able to edit our github-hosted site

This is specfically referring to editing a site [like this](https://biovcnet.github.io/), or the pages at that site like the [people page](https://biovcnet.github.io/_pages/people/) (which will be the example here). This is different than editing a github wiki [like this](https://github.com/biovcnet/biovcnet.github.io/wiki) – that is easiest to do directly at the wiki with the "Edit" and "New Page" buttons at the top right because there is much less web stuff going on under those wiki pages (less weird rendering things can go wrong, and easy to preview while editing).

Changing a github-hosted site can be done directly at the github code area for it, like [here](https://github.com/biovcnet/biovcnet.github.io), by editing and uploading files, or it can be done locally at your computer by using `git` to "clone" the repository, making the changes we want, and using a program called [Jekyll](https://jekyllrb.com/) to render our local version of the site temporarily so we can check it out and make sure things are looking the way we expect them to look. That can be particularly helpful if we want to maybe make our own [github-hosted site](https://help.github.com/en/github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll), or if we want to make large changes/edits to a site.

[Jekyll](https://jekyllrb.com/) is the primary program used to do this, and they have really good documentation. Instructions for different OSs start [here](https://jekyllrb.com/docs/installation/). Despite their good documentation, it can be easy to run into some snags still. So here's a walkthrough built off of their documentation with some additional notes of what we've done recently when trying to get this set up. If you hit any snags and want some help trouble-shooting, feel free to message me (Mike Lee) on slack or email me: [e-mail]

---

**OS NOTE:** Right now this is only for Mac computers because we haven't gone through it with Windows yet, but I'd start with their [instructions here](https://jekyllrb.com/docs/installation/windows/), and please let us know if you have to iron out any snags on the way that might be helpful to others so we can add them here!

---

[TOC]

---
<center>
<b>Except for where noted, this is all performed at the terminal.</b>
</center>

---

## 1. Installing/checking for xcode-select
If this is already installed, running this won't cause any problems, it will just tell us it is, so let's run this:

xcode-select --install

## 2. Ruby version checking
Jekyll needs to have a ruby version >= than 2.4.0, we can see what we have on our system with this:

ruby -v

If we have less than 2.4.0, then we need to install a newer version and we should go to [**step 2a**](https://hackmd.io/m1_7qvwQSRqyhDZC7CetiQ?view#2a-Installing-newer-ruby-version). If we have a version >= 2.4.0, then we can go to [**step 3**](https://hackmd.io/m1_7qvwQSRqyhDZC7CetiQ?view#3-Installing-bundler-and-jekyll).

### 2a. Installing newer ruby version (if needed)
It seems the easiest way to do this is with [Homebrew](https://brew.sh/) (a package manager for Mac OSs), we can install Homebrew with the following:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

And we can now install a newer ruby like this:

brew install ruby

And we are now adding that to [our PATH](https://astrobiomike.github.io/unix/modifying_your_path) with this line, and then refreshing our terminal environment to incorporate this change:

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.bash_profile

source ~/.bash_profile

Now our ruby version should be newer:

ruby -v

And we want to add one more thing to [our PATH](https://astrobiomike.github.io/unix/modifying_your_path) before we move on that is based on our ruby version. It is going to look something like this following line, but we will need to change the first two "X"s to match the first two digits of the ruby version that we have:

echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

For instance, my ruby version says `ruby 2.4.1p111 (2017-03-22 revision 58053) [x86_64-darwin18]`, so I would change the "X.X.0" in the above command to be "2.4.0".

## 3. Installing bundler and jekyll
I don't really get all these terms in the ruby world, but if interested at all, I *think* "gems" are individual packages, and "bundler" handles many gems at once. So here we are attempting to install a gem called bundler and the gem that holds jekyll ¯\_(ツ)_/¯

gem install --user-install bundler jekyll

This has not worked perfectly so far, and some folks have had a failure on installing jekyll while the bundler successfully installs. If that happens, conda may help, so feel free to try that, or don't worry about it for now, and we'll try installing jekyll again a different way in a little bit.

### 3a. Conda may help
[Conda](https://docs.conda.io/en/latest/) may be an easy path for some folks with Mac Mojave. If we don't yet have it, we can get and install conda with the following:

  ### if wanted/needed ###
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh

bash Miniconda3-latest-MacOSX-x86_64.sh
  ### if wanted/needed ###

Then we can create a new environment and install jekyll like so:

  ### if wanted/needed ###
conda create -n github-pages -y

conda activate github-pages

conda install -c conda-forge rb-jekyll
  ### if wanted/needed ###

## 4. Getting the site repository
We need the program `git` in order to be able to do this. We can check to see if we have `git` like so:

git --version

That will return a message with "command not found" if we do not have it. If we have don't have `git`, let's go to [**step 4a**](https://hackmd.io/@astrobiomike/bvcn-edit-site#4a-Installing-git-if-needed) to install it. If we do have `git`, let's jump to [**step 4b**](https://hackmd.io/@astrobiomike/bvcn-edit-site#4b-Cloning-the-repository).

### 4a. Installing `git` (if needed)
The easiest way to install `git` is probably with [Homebrew](https://brew.sh/) (a package manager for Mac OSs). If we don't have Homebrew and didn't install it above yet, we can install it with the following:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

And we can now install `git` like this:

brew install git

### 4b. Cloning the repository
We can clone a git repository with the command `git clone` followed by the address to it. First, in our terminal, let's navigate to somewhere we want the repository to go on our computer. Then we can copy the needed address from the repo we want from the "Clone or download" dropdown menu on the main github repo page, for example [here](https://github.com/biovcnet/biovcnet.github.io):

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/nWsFQs9.png">
</div>
<br>
<br>

Clicking the copy-to-clipboard icon will copy the address we need, and then this command will clone it to our computer:

git clone https://github.com/biovcnet/biovcnet.github.io.git

When that is done we want to change into that directory:

cd biovcnet.github.io/

## 5. Making a new branch
If we run `git status` now, it will tell us we are on the master branch. Here is one way we can create our own branch to work in, and change into it (you should name this something else following the `-b` flag 🙂 ):

git checkout -b mike-lee

Now if we run `git status`, it will tell us we are on this new branch.

## 6. Rendering the site locally
Now we are going to try to load up our own version of the site. We do this with the following command:

jekyll serve

**If** this gives us a problem and suggests running it as `bundle exec jekyll serve`, then trying it that way will likely work:

  ### if needed ###
bundle exec jekyll serve
  ### if needed ###

**If** we got a "command not found" error because we are still missing Jekyll due to it possibly failing above, then now we are going to try to install it this way:

  ### if needed ###
bundle install
  ### if needed ###

And then try `jekyll serve` or if needed `bundle exec jekyll serve` again.

**If** there is still trouble, and we are seeing an error message noting `ffi` is having problems, we have found on Mojave that [this advice](https://github.com/ffi/ffi/issues/653#issuecomment-518062877) has worked, so we can try this:

  ### if needed ###
  # relies on Homebrew so return to example above to install that if 
  # needed, it's in step 2a
brew reinstal libffi
export LDFLAGS="-L/usr/local/opt/libffi/lib"
export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"
gem install jekyll
  ### if needed ###

**If** there is still trouble, and it wasn't tried earlier, now is a good time to hope conda can save us, and we can try what is listed up at [step 3a above](https://hackmd.io/@astrobiomike/bvcn-edit-site#3a-Conda-may-help).

When the `jekyll serve` command or `bundle exec jekyll serve` command works properly, it will print out some stuff and then eventually be on hold with something that looks like this:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/BNucuVX.png">
</div>
<br>
<br>

This may take a few minutes the first time, but will only take seconds after that.

At this point we can copy and paste the link it says is the address of the server, "http://127.0.0.1:4000/" here, into our web browser and see our local version of the site. And if we click on the People tab, which at this point will look the same as it does on the regular site:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/OWjzZBU.png">
</div>
<br>
<br>

To avoid being confused if viewing both (our local version and the actual live site), it can help to note the address in the address bar. Our local one starts with "localhost" or might start with numbers depending on the browser being used, whereas the main one will have the regular address.

## 7. Making some changes

In the case of this site, the document that holds the "People" page, is in the subdirectory called "_pages" and the file name is "people.md". We can edit that with any old text editor, but it can be easier using something designed for markdown (markdown is like a hybrid of html and plain text that is convenient for working on general web pages).

### 7a. Grabbing a MarkDown editor
One possible markdown editor that I use on a Mac is called [MacDown](https://macdown.uranusjr.com/). That can be downloaded from the bottom of that site and unzipped just by clicking. It'd then probably be a good idea to move the program somewhere like your computer's Applications directory. When that is done, open the MacDown program, click on "MacDown" at the top left of the screen (very top left near the Apple logo), then "Preferences", then "Terminal", and click to install so we can use this program from the command line:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/gnlD6ZU.png">
</div>
<br>
<br>

Now back at our terminal, we want to keep the local server running, but get a new terminal in this same directory so we can do some work there. We can do that with `command + t` in our local server terminal, or just open a new one and navigate back to the main `biovcnet.github.io` directory. Once there, we can open the `_pages/people.md` document to edit it like so:

macdown _pages/people.md

And that should pop open a MacDown document that looks something like this:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/PB4XKwC.png">
</div>
<br>
<br>

In this view, the part we edit is on the left, and the right side tries to give us a slight preview of what we are doing (but our real preview as we start making changes will still be in the web browser). The way things are set up right now, it is normal for the images to be missing in some cases in the preview on the right side.

### 7b. Adding our profile to the People page

Let's say we want to add our profile now. In this case we can just copy the formatting from another individual and add it wherever we want it. So let's copy Ben Tully's block of info and paste it at the bottom of the document:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/M9iJZn2.png">
</div>
<br>
<br>

And now let's start changing it (we'll get to the picture next, so skip that for now), but say here's what mine looks like after some changes:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/WK7pFJv.png">
</div>
<br>
<br>

And if we save that document now in the MacDown program, the locally rendered site will update, and refreshing the People page now has this new addition at the bottom:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/zPXIHZ8.png">
</div>
<br>
<br>

On to the picture!

### 7c. Adding in our picture
There are different ways to do this if our picture is already hosted somewhere online, but to add a picture from our local computer, we need to add it to this repository. We are keeping all these images in the "images" subdirectory, so we just need to add the image we want to that subdirectory (being sure it has a unique name), and then change the code to point at our picture based on that unique file name. The picture part in the code is near the top written in html,`<img align...>`. Note that Ben's picture has this in it: `src="/images/benjtully.jpg"`. We just need to change that part of the code to match our file name. I copied an image into the `biovcnet.github.io/images/` directory called `ada-lovelace.jpg` (this can be done in any way, drag and drop in a Finder window, or commands at the command line). So now changing the image code to say `src="/images/ada-lovelace.jpg"`:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/pNzjSP2.png">
</div>
<br>
<br>

And saving the MacDown document, then refreshing the local People page, we can see our new photo:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/aG1brmH.png">
</div>
<br>
<br>

Great! But this is still just our local version, so once we have things how we want, we then need to do some more `git` work to get it up on the main site. If we are done previewing what the site looks like, we can hit `ctrl + c` to cancel the `jekyll serve` command that is constantly rendering the site.

## 8. Adding, committing, pushing, pulling, merging (bla bla bla `git` stuff)

I have used `git` and github for a few years, to do quite a bit, but I'm still not familiar with all the pushing and pulling and whatnot. So don't worry if that's all pretty nebulous, just using these things without having our heads comfortably wrapped around the whole ecosystem very much seems to be the norm to me 🙂

Right now we made these changes in our local clone of the repository, on a new branch (the main site is on a branch called "master", and we are working in a branch called, whatever we named it above). We want to save these changes to our branch, and then "push" that branch to the main repo so it is stored there also, and then we'll submit a "Pull-request" at the github site that we can then merge into the main thing and our changes will then finally appear on the main site.

When we ran `git status` at first, it just said the name of our branch. Now it should tell us there have been some changes:

git status

It should still say we are on our new branch at the top, and then say we've modified "_pages/people.md", and the image we added will probably be listed "Untracked files" (because it didn't exist yet, so `git` doesn't have it tagged or anything yet). We want to add these things to be "staged to commit", we can do that like so:

git add *

(If we wanted to only add some files, we could list them out one at a time to that command or separated by spaces. You will also see some things that are not added due to being in a `.gitignore` file, that's normal.)

Now `git status` will tell us "Changes to be committed", and it will list our files there, and we are ready to actually commit them to our branch. We can do that with `git commit` like follows, where the `-m` flag precedes a little message we want to add about what we are doing:

git commit -m "adding Ada to people page"

And now we want to push our new branch to the main repository hosted on github, so we do that with `git push` and specifying "origin" and then our new branch name:

git push origin mike-lee

This may require you to enter your github username and password.

Now if we go to the [main github site for this repo](https://github.com/biovcnet/biovcnet.github.io), we can see our branch appears in the list of branches now, e.g.:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/ZMylq5o.png">
</div>
<br>
<br>

If we click on our branch, it will change to it in the repo, and then we want to click on "New pull request":

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/FpOduNA.png">
</div>
<br>
<br>

This will open a new page that looks like this and has info about our changes, and we want to then change the "base repository" to "biovcnet/biovcnet.github.io" like so:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/C3WWmNJ.png">
</div>
<br>
<br>

That should cause the page to automatically reload and then look something like this:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/34VUuBj.png">
</div>
<br>
<br>

And then we can click "Create pull request" to enter it as a pull request. Then clicking on the "Pull requests" tab at the top of the github page, we should be able to see it in the list of open pull requests:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/OLkXxMG.png">
</div>
<br>
<br>

Then clicking on it, we may be able to merge it ourselves if we want (that is merge our new branch into the master one) by clicking "Merge pull request", or we can Assign someone on the right side:

<br>
<div style="text-align:center">
<img src="https://i.imgur.com/ZcqkSEZ.png">
</div>
<br>
<br>

Feel free to assign me if you'd like so I get notified and I'll merge it ASAP!

# More snags?
If you get stuck on something and want some help trouble-shooting, I'd be happy to try to help out. Feel free to message me (Mike Lee) in our slack group, or email me: [e-mail]

# What a pain!
That does seem like a lot, and like lots of things it can seem extra messy and excesive at first, but it does get easier 🙂

Having this Jekyll infrastructure setup means you can now pull down and mess with any github-hosted site you want, or [make your own](https://help.github.com/en/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll)! GitHub hosts one site for free for all users!