previous episode

Cloud from A to Z

First Jekyll site

next episode

Overview

Teaching: 20 min
Exercises: 10 min
Questions

  • Why use Jekyll?

  • How does Jekyll work?

  • What is YAML?

  • What is an IP address?

  • How do you use ready made themes?

  • How do you configure your site?

Objectives

  • Log into a remote VM

  • Download a Jekyll theme

  • Create your first Jekyll site

Why Jekyll?

There are a growing number of static website generators. For this workshop we have chosen Jekyll because it has been around a while. First released in 2008 and was one of the first in the new trend of static website generators. It was also adopted by github which is a free service for hosting git repositories which is very widely used. With this background we can see that Jekyll is a pretty solid project and will be supported well into the future.

What is Git? Very quickly, Git is a program that helps manage and track changes to sets of files (mainly plain text files) and facilitates parallel editing of these by many authors and later merging of these changes together. To learn more about git, Software Carpentry has an excellent lesson on git. Fully teaching Git is beyond the scope of this workshop but it is highly recommended you look into it. If you do track changes to your website using git you can create a github repository and upload your site there and github will provide free website hosting with no need to manage a web server yourself.

Later we will look very quickly at how git and github can be used to host our Jekyll websites, but we will not dive into the gory details needed to fully understand and utilize git.

Finally these course materials you are reading now are generated by Jekyll and are hosted on github.

How does Jekyll work?

Jekyll creates a static website (HTML, CSS, and javascript) from templates and themes (HTML, CSS, and javascript), and content written in Markdown. Once this static website is generated it can be published to the web or viewed locally in your web browser.

To create a Jekyll website you need to choose the starting theme and edit plain text files in a format called Markdown. Once you are happy with your changes, you need to generate the static website by running a command in a shell, something like:

$ jekyll build -d <web-directory>

Quick review of the shell

The shell is a program where users can type commands. These commands run programs which can do simple things like provide information about files and directories on your computer or more complex tasks such as software installation and configuration.

Start up your shell (a.k.a. a terminal) and you will see a prompt. A prompt is usually some text and characters to indicate that the shell is waiting for you to enter a command. In this lesson we will use the “$” to indicate a prompt which is likely somewhat different from what you see in your shell.

Accessing your terminal

Windows: startup mobaXterm and then click Start local terminal

Mac: search in spotlight for terminal click on search result terminal

Linux: if using a newer version of Ubuntu try searching for terminal with unity’s search tool (usually in the top left of the screen on the tool bar)

$

First lets find out where we are by typing the command pwd, then press the Enter key to send the command to the shell.

$ pwd

/home/cgeroux

More specifically, when we type pwd and press the Enter key, the shell:

  1. finds a program called pwd,
  2. runs that program,
  3. displays that program’s output, then
  4. displays a new prompt to tell us that it’s ready for more commands.

The pwd command’s output is the present working directory. In this case /home/cgeroux. This directory is known as a home directory where settings, files and programs for the user cgeroux are kept. The string /home/cgeroux is known as a path which indicates a specific file or directory within a file system. File systems have a tree like structure, starting at the root of the file system (/) and branching out from there. Each new directory creates a new branch in the file system. Directories are seperated in a path by forward slashes, / so that a directory inside another one can be represented like /home in this case, the home directory is inside the root directory /. Adding another directory in depth to the path we have /home/cgeroux which is a directory inside the home directory.

To change your present working directory there is a command called cd for change directory. It takes one argument which specifies which directory to change to.

$ cd /home
$ pwd

/home

as you can see the pwd command now tells you that you are in the directory /home. Lets now move back to our home directory. Your home directory name will be different from mine and be the output from the first execution of pwd.

$ cd /home/cgeroux

There is a common file system layout across most Linux systems. The below figure shows an overview of some of the more relevant directories within a Linux file system for this lesson, however there are more directories than are shown here.

file system

Home Directory Variation

The home directory path will look different on different operating systems. On Linux it might look like /home/cgeroux but on windows using mobaXterm it might look like /home/mobaxterm or on a Mac like /Users/cgeroux.

So far we have been using what are known as absolute paths. An absolute path is a path which starts with a / that is they start from the root of the file system. Absolute paths reference the same location no matter where they are used. There are also paths known as relative paths which are relative to your current working directory. These can either start with a . to indicate the current directory (e.g. ./Documents/pictures), or the can just start with the directory name (e.g. Documents/pictures). This is different from an absolute directory which always begins with a /.

In addition to the . shorthand for the current directory there is a .. shorthand for parent directory of the current directory. Lets try moving up to the parent directory using a relative path using the .. shorthand.

$ cd ..
$ pwd

/home

Then back to our home directory.

$ cd cgeroux

Connecting to a workshop VM

We just ran some commands in our shell on our laptops, however, to work on our Jekyll websites we are going to work on a remote computer already setup on an Alliance cloud for us with Jekyll already installed.

We can interact with this remote computer in the same way we have been interacting with our local laptops, using a shell. To interact with a remote computer using a shell we must first connect to it using a program called ssh, which is short for secure shell. This command allows you to type commands as we did on our laptops but the commands are executed and affect the remote computer. It is secure because it encrypts data sent to and from the remote computer so that people intercepting these communications can not decipher them.

Before we run the ssh command lets take a look at the manual entry for it.

$ man ssh

SSH(1)                      General Commands Manual                     SSH(1)

NAME
     ssh - OpenSSH SSH client (remote login program)

SYNOPSIS
     ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec]
         [-D [bind_address:]port] [-E log_file] [-e escape_char]
         [-F configfile] [-I pkcs11] [-i identity_file]
         [-L [bind_address:]port:host:hostport] [-l login_name] [-m mac_spec]
         [-O ctl_cmd] [-o option] [-p port]
         [-Q cipher | cipher-auth | mac | kex | key]
         [-R [bind_address:]port:host:hostport] [-S ctl_path] [-W host:port]
         [-w local_tun[:remote_tun]] [user@]hostname [command]
...

Many commands have manual pages, so executing the command man <some-command-name> will display information about that command, how to use it, and the options available for that command. Options for a command are specified after the command with a - followed directly by the option identifier for example, -d.

Run the ssh command below replacing <username> with the username you have been provided with for the course and <remote-ip> with the IP address identifying the workshop remote computer.

An IP address is a set of 4 numbers separated by .like 216.318.22.56, with each number ranging between 0 and 255. IP addresses act like postal addresses to direct messages to the correct computer connected to the internet.

$ ssh <username>@<remote-ip>

Warning: Permanently added '<remote-ip>' (RSA) to the list of known hosts.
<username>@<remote-ip>'s password:

At the password: prompt enter the password you have been provided with for the course.

Welcome to Ubuntu 20.04.2 LTS (GNU/Linux 5.4.0-73-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage
...

Start with a theme

Lets create our first site using a pre-made custom theme so it looks nicer than the built in standard Jekyll theme. There are a number of places to find Jekyll themes:

I found one I like on jekyllthemes.io, called Forty, lets use this theme.

To use it we need to download it onto our VM. In order to do that we need to get a URL to download it from. A little bit lower on the page there is a link that says “Get Forty on GitHub”. If we click that it will take us to the theme’s github page. We can get a download URL from there by clicking the “Code” drop down box, right clicking on the “Download ZIP” link and selecting “Copy link address”.

Now we can download it to our VM by using the wget command and pasting the link we copied to our clip board into our SSH terminal on our VM. Then unzip the newly downloaded file with the unzip command and change into that directory. 

$ wget https://github.com/andrewbanchich/forty-jekyll-theme/archive/master.zip
$ unzip master.zip
$ cd forty-jekyll-theme-master

There are a few minor configuration settings we have to make in order for that theme to work with our web-server. Configuration settings for Jekyll sites are generally in the _config.yml file. This is a YAML file (YAML Ain’t Markup Language) (see: yaml.org). Very briefly, a YAML file is a way of specifying key value pairs in a standardized format so that computer programs and people can easily read them. These key value pairs have a format like key:value, where the key name and it’s value are separated by a colon, :. There must be a space between the colon, : and the value.

In addition, lines which begin with a # are comment lines. These lines add useful information for people reading and editing these YAML files but are usually ignored by programs reading these files.

$ nano _config.yml

# site settings
title: Forty
.
.
.
baseurl: "/forty-jekyll-theme" # the subpath of your site, e.g. /blog
.
.
.

To have the site generate correctly we only need to change one value, for the key: baseurl. This value tells the site how to find things within its own site. Initially this has the value /forty-jekyll-theme. This tells the site that it is located in the directory “forty-jekyll-theme” in the root directory of our web site. In our case our root web directory is /var/www/html on our VM and each user has their own directory named after their username. For example user01 would have their website at /var/www/html/user01. So we need to set the key baseurl to be your username. For example if you logged on with user01 you would want to set baseurl to be user01. After editing the _config.yml file it should look like this:

# site settings
title: Forty
.
.
.
baseurl: "/<your-username>" # the subpath of your site, e.g. /blog
.
.
.

with the username you logged in with instead of /<your-username>

Then save the and exit the editor by pressing ^ (control) and x keys simultaneously. This will ask if you want to “Save modified buffer?” to which you answer Y for yes. It will then check to see if you want use the same file name, which we do, so press return or enter to confirm. You should now be back at the command prompt.

Use the following command to publish it to our web-server’s root directory.

$ jekyll build -d /var/www/html/<your-username>

This command generates the site from the contents of the current working directory and places the newly created site in the /var/www/html/<your-username> directory.

Finally visit your new site at your VM’s IP address in your browser with your username appended (e.g. /user01) to see your new Jekyll site.

First Jekyll Site

Absolute vs Relative Paths

If the present working directory is /Users/amanda/data/, which of the following commands could Amanda use to navigate to her home directory, which is /Users/amanda?

  1. cd .
  2. cd /
  3. cd /home/amanda
  4. cd ../..
  5. cd ~
  6. cd home
  7. cd ~/data/..
  8. cd
  9. cd ..

Solution

  1. No: . stands for the current directory.
  2. No: / stands for the root directory.
  3. No: Amanda’s home directory is /Users/amanda.
  4. No: this goes up two levels, i.e. ends in /Users.
  5. Yes: ~ stands for the user’s home directory, in this case /Users/amanda.
  6. No: this would navigate into a directory home in the current directory if it exists.
  7. Yes: unnecessarily complicated, but correct.
  8. Yes: shortcut to go back to the user’s home directory.
  9. Yes: goes up one level.

Relative Path Resolution

Using the filesystem diagram below, if pwd displays /Users/thing, what will ls ../backup display?

  1. ../backup: No such file or directory
  2. 2012-12-01 2013-01-08 2013-01-27
  3. 2012-12-01/ 2013-01-08/ 2013-01-27/
  4. original pnas_final pnas_sub

File System for Challenge Questions

Solution

  1. No: there is a directory backup in /Users.
  2. No: this is the content of Users/thing/backup, but with .. we asked for one level further up.
  3. No: see previous explanation. Also, we did not specify -F to display / at the end of the directory names.
  4. Yes: ../backup refers to /Users/backup.

Key Points

previous episode

next episode