Since this is the very first post on this blog, and I am not sure how many posts will follow this one, I’ve decided to start off by just explaining how this blog has been setup and how you, too, can have your very own shiny new blog on github pages.

For what it’s worth, I’ve discovered there’s quite a few blog posts out there that talk through all of the steps outlined below, in quite a bit more detail. You can consider this the TL;DR version of those posts.

Domain Setup: Github.io

This is super straight forward, and there’s really nothing more that I can add to the documentation from Github Pages.

Jekyll Installation

This is my first time using Jekyll and I have to say that I’m really impressed by the sheer simplicity and ease of use.

As a windows user, setting up my local blogging environment came down to the following few steps

• (If you don’t already have this..) Install chocolatey. In a powershell window, run the following command

PS:\>iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))

• Install ruby

choco install ruby -y

• Install jekyll

gem install jekyll

Setup your blog

The setup and customization of your blog is where you will really start to get to know jekyll. Start off first by creating you new blog

jekyll new myblog

What this will do will create a folder structure similar to the below

.
├── _config.yml
├── _drafts
|   └── this-is-a-draft.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   └── 2016-03-01-this-is-a-post.markdown
├── _site
├── .jekyll-metadata
└── index.html

Right off the bat, you can run this sample site to see what the blog looks like by running the following comand

jekyll serve

This will start off a running instance of the generated html for the site, and you will be able to see this at http://localhost:4000/

To see draft posts

jekyll serve --drafts

At a high level, the _layouts folder contains (as expected) the overall layouts of the site. The layouts themselves are mostly html with a bit of liquid tags mixed in. Layouts themselves mostly serve as placeholders for html includes that exist in the _includes folder. With these two building blocks in place, changing the look and feel of the site boils down to one of two things

• To change the overall organization of the page, tweak the layout.
• To add additional snippets of reusable html, javascript, css into the layout, create a new include file and reference that in the layout.

Creating a post

Blog posts and pages in general can be created using markdown or html. The only thing the page really needs is the Front Matter block that specifies some attributes of the page like the layout to be used, tags on the page etc. For example, here’s the Front Matter block for this page.

---
layout: post
title: "Setting up this blog"
summary: This post talks about the process followed to setup a blog on github pages using jekyll
tags: [jekyll,blogging,github pages, discus]
---

You can create pages in the _drafts folder and review the page using the jekyll serve --drafts command mentioned above.

Once you’re good with the way the page looks, you can copy the draft to the _posts folder. Remember that posts need to use the following naming convention YEAR-MONTH-DAY-title.MARKUP

Publishing

All you really need to do is use the following command

jekyll build --destination <destination>

Check the output of the build to the repo for github page, and voila you’re done!

Hopefully this guide helps you along as your way as you attempt to start your own experiments with Jekyll. If you’ve found this useful or have some additional tips for jekyll users, please leave me a comment or hit me up on twitter.

Cheers!