Blogging with Jekyll!

I just finished setting up my blog. It’s still very much green, as am I, still I decided to begin my ramblings.


What is GitHub Pages?

GitHub Pages is a static site hosting service, so they say. The idea is basically to have a static site hosted by GitHub Pages from a GitHub repository. The emphasis here is on static site. It doesn’t support server side code.

You might want to take a look at the terms of service and community guidelines, just so everyone’s clear.

Dr. Jekyll powers GitHub Pages. Jekyll is a simple, blog-aware, static site generator. They did a better job at explaining it than I would, so I’ll leave it at that.

We are going to set up our GitHub blog to run locally, then push it to GitHub.

Assumptions:

  • You know about and have used GitHub before; which would imply
  • You’re comfy with the terminal

Ok, shall we begin…

Note: Comments begin with the hash tag (#…)

Run GitHub blog locally:

In your terminal;

Install Jekyll and Bundler gems via RubyGems:

gem install jekyll bundler

Create a new Jekyll site at ./name_of_blog. This location would be the root directory of your blog:

jekyll new name_of_blog

Change into your new directory:

cd name_of_blog

Next, edit your Gemfile. Within name_of_blog directory is a file called Gemfile. Open it with your favorite editor;

Remove or comment Jekyll gem:

# Comment jekyll gem
# gem "jekyll", "3.4.1"

Delete the # at the beginning of this line:

gem "github-pages", group: :jekyll_plugins

Then in the terminal, update bundle and run the server`:

# Rebuild snapshot
bundle update

# Run the site locally
jekyll serve

Now go to http://localhost:4000. The site should be running locally at that address.

Push the site to GitHub:

# Initialize your site directory as a Git repository
git init

At this point, we assume we have created a spanking new repository on GitHub. If we haven’t, here’s how to create a repo.

# Connect your remote repository on GitHub to your local repository
git remote add origin https://github.com/username-or-organization-name/your-remote-repository-name.git

One can make certain edits at this stage. Some edits might include:

  • Editing the blog title / email / description / etc in the _config.yml file
  • Creating a README.md file
  • Etc
# Add or stage your changes
git add -p

The -p flag steps through your changes, allowing you see what was changed and giving you the option to accept or reject that change.

# Commit your changes with a comment
~/name_of_blog$ git commit -m "Edit or update site"

Push your changes to your remote repository on GitHub. Because this is the first push to the newly created remote branch, we add the upstream tracking reference using the -u flag. After pushing, the local branch is linked to the remote branch, and the commands git pull or git push can be used without any arguments.

# Pushing changes...
git push -u origin master

At this point, all your changes should be in the remote repository. To take our site live,

  • Click the “Settings” button at the top right of your repository page (on GitHub)
  • Scroll to the GitHub Pages, Source section, click on the drop-down list and select master branch
  • Click on the Save button to the right of the drop-down list

You should see the message: Your site is published at https://username.github.io/your-remote-repository-name/

If you don’t see this message, please refresh the page and check again.

Your blog should now be live.

__Note__: As of 5th March 2017, the gem `github-pages` comes with jekyll version 3.3.1
Changing the theme in the repository's settings page causes the app to break. 
Removing the includes in the `about.md` page fixes this.