In this lab, you will learn about Jekyll and Markdown to create a blog on github.io. You will gain exposure to a framework that generates websites, continue building experience with GitHub and GitKraken, familiarize yourself with the terminal method for installing software, and host a local server.
Navigate to Github.com and create a New repository
called csci340blog, with the following options:
You should now have a shiny new repository, and GitHub will direct you to its main page.
Click on the Setting tab near the top of the repository page. Scroll down to the
GitHub Pages section, and set the Source to be the master branch.
This way, your current repository will be processed as a subdirectory of your
username.github.io website.
Now, clone the repository locally with GitKraken as you did in the last lab. Find
csci340blog in your linked GitHub.com account, navigate to or create a good
directory, and click the "Clone the repo!" button.
Open the Terminal or Command Prompt and navigate to your new local repository directory.
Next, you will need to install Ruby. You can do this in a few ways. Follow these instructions to get Ruby on your computer.
To check that Ruby is properly installed, from the command line, type
ruby --version
With Ruby installed, we need to get an extension called bundler. We can install bundler with the gem package manager. Type the following line at the command line:
gem install bundler
Depending on how you installed Ruby, you might need to use sudo in front
of the previous line to properly execute the installation.
One last piece. Open a new text file called Gemfile in your repository.
In this file, type the following two lines, and save the file.
source 'https://rubygems.org' gem 'github-pages', group: :jekyll_plugins
Finally, we can install Jekyll by executing the following command.
bundle install
Now with all the right software installed on your computer, you can quickly create the default Jekyll blog framework. Run the following command from the terminal, making sure you are located in the directory corresponding to your cloned repository.
bundle exec jekyll _3.3.0_ new . --force
This should create many files and directories for you to explore. Open up the folder in Atom to browse through the files.
To see your blog in action, we will first look at your blog locally. Again, in the directory corresponding to your cloned repository, run the following command:
bundle exec jekyll serve
This will start a local server on your computer, and when it is running, you should be
able to view your blog through the url http://127.0.0.1:4000/.
Finally, let's put this code back in your public repository on GitHub so it is viewable anywhere on the web. Using GitKraken, Stage all the changed made by installing the blog template, Commit them, and then Push your commit.
Now, you can look at your blog on GitHub Pages, using http://username.github.io/csci340blog.
Hmm... there are a few things we need to fix before it looks right on the web, because the blog is located in a subdirectory.
Edit the Gemfile. Comment out the following line:
gem "jekyll", "~> 3.8.5"
And uncomment this line:
gem "github-pages", group: :jekyll_plugins
Using GitKraken, Stage your changes, Commit them, and then Push your commit.
Next, edit the file named _config.yml. Find the line concerning baseurl,
and edit it to say
baseurl "/csci340blog"
You should notice that this _config.yml also contains some basic info that
is displayed on your blog. Edit the following lines to personalize this information.
title
email
description
twitter_username
github_username
Using GitKraken, Stage your changes, Commit them, and then Push your commit.
Now, the links should work on your blog up at GitHub Pages, using http://username.github.io/csci340blog.
Our last step is to use Markdown to start writing blog posts. Future assignments will require you to make post on this blog.
You will be adding files to the_posts/ directory, following the
YYYY-MM-DD-descriptive-tile.markdown naming conventions found in the "Welcome to Jekyll" post.
These posts will be written in the Markdown language, which is then converted to HTML.
Write a new post titled "Introduction Post", describing your setup experience in this blog. What parts were new to you? What parts did you struggle with? What parts still do not make sense? What are you looking forward to? Your post must include at least two links and a list.
Create a _drafts/ folder, and move the "Welcome to Jekyll" file into
this new drafts directory.
As you write blog posts for this and future assignments, I recommend using the local server method shown above for previewing and tweaking your text as you make commits. Once you are happy with your text, push it to github repository.
Using GitKraken, Stage your changes, Commit them, and then Push your commit.
View your post at http://username.github.io/csci340blog to make sure
everything is correct.
Send an email to Dr. Goadrich with a link to your first post up on GitHub pages.
Completing Steps 1-5 earn you a C. Step 6 earns an A.