Kyle Stratis Software Developer in Tallahassee, FL

Setting Up an Elegant Blog with Github Pages, Jekyll, and Poole; Part II

I guess it’s time to talk a little bit about the finishing touches I did to customize this site further beyond what Poole and Layon offer.


I used the following sites for help with these customizations, ideas, code, and more. Be sure to visit them and poke around a bit:

Enabling Disqus Comments

First, visit the Disqus website, set up an account, and log in. Upon logging in you will be brought to your dashboard. Click the gear in the top right corner, and in the dropdown box select “Add Disqus to Site.” Follow the commands until you get to the unique code for your disqus comments.

Now, shifting forcus to your site, you’ll want to add the following line to _layouts/default.html:

{% include comments.html %}

If you take a look at my default layout you will see that this is placed in the content container div underneath the liquid tag for the post’s (or page’s) content. The relevant code:

<div class="container content">
  {{ content }}
  {% include comments.html %}

The parent divs are wider than the content container, and so adding the include statement outside of this one will make the comments section (once you implement it in comments.html) stretch across the entire page, rather than being confined to the content’s area.

Now that you are armed with Disqus’s universal code and you have set the location of your comments in the HTML, you can create comments.html in the _includes folder. Here’s what my comments.html looks like:

{% if page.comments %}
<div id="disqus_thread"></div>
<script type="text/javascript">
    var disqus_shortname = %%%YOUR USER NAME HERE%%%;
    var disqus_identifier = "{{ site.disqusid }}{{ page.url | replace:'index.html','' }}";
    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = '//' + disqus_shortname + '';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
<noscript>Please enable JavaScript to view the <a href="" rel="nofollow">comments powered by Disqus.</a></noscript>
{% endif %}

The first thing you see is this liquid tag:

{% if page.comments %}

which is paired with

{% endif %}

at the end of the file. This will run all the code it encloses if the comments is set to true in the YAML frontmatter of whichever page or post is being generated. After that is the universal code (slightly modified) provided by Disqus, and the value of the disqus_shortname variable is provided by Disqus (and is simply your Disqus username). Don’t forget to set Comments to true or false in your YAML frontmatter!

The disqus_identifier configuration variable does not come from the universal code, but it helps Disqus return the appropriate thread for your article. See more about Disqus configuration variables here.

This code was adapted from Joshua Lande’s excellent article.

Enabling Google Analytics

This is very straightforward and follows the same pattern as setting up the Disqus comments. Go to the Google Analytics site, sign up for an account if you don’t have one already, use universal tracking and copy the code that they provide. Create a file in the _includes folder and name it something like google_analytics.html. Paste in the code Google gave you and save the file. Now all that’s left is to open layouts/default.html and add the following line:

{% include google_analytics.html %}


A favicon can be built an an image editor like GIMP, and there are a number of sites that have pre-made designs you can choose from. Save your favicon.ico to the folder public (which should have a placeholder favicon already present), then head over to _includes/head.html and and verify that the reference to your favicon exists:

<link rel="shortcut icon" href="{{ site.baseurl }}public/favicon.ico">

Tags Page

This page was modified from Patrick Steadman’s site that I mentioned earlier. You can store this page in the root folder for your site as tags.html. A slight modification from his version was to comment out the code that displays the number of articles with a given tag, as you can see in my repo. Feel free to copy and paste the code directly, and note how the YAML frontmatter declares it a page rather than a post.

I again drew inspiration from Patrick Steadman’s design here, which is clean and balanced, and has some nice features not present in the default Lanyon sidebar. Let’s first take a look at the sidebar and its structure. At the top I have a pretty picture of myself cropped as a circle, below which I have a some nice attractive icons that link to my various social networks. Below that still is a short tagline, then site navigation, version number, and a copyright notice (don’t worry, this is just for the blog content, the actual code is available under MIT licensing). You can find the sidebar code in _includes/sidebar.html. All of the code in the following subsections will be within the first div of this file, aside from the CSS file:

<div class="sidebar" id="sidebar">

Custom CSS

First, though, we will want to apply some custom CSS for the sidebar to allow for a few aesthetic features like opacity. To do this, we will create a new file in public/css/ called custom.css. Save the empty file as it is, then open head.html in _includes and add the following line under the CSS comment:

<link rel="stylesheet" href="">

Save that, now go back to your custom CSS file, and add the lines below. Feel free to play with the values to get the effect that is most pleasing to your eye, this is your site after all! Since you’ve got the CSS file linked, you can use jekyll serve in your terminal to test your changes to the CSS.

.sidebar {
       opacity: 0.8;
.sidebar:hover {
       opacity: 1.0;

This will simply set the default and hover opacities for the sidebar, tweak these to what looks pleasing to your eye.

.sidebar-logo {
      padding: 1.5rem;
.sidebar-logo img {
      border-radius: 50%;
      -moz-border-radius: 50%;
      -webkit-border-radius: 50%;
      width: 160px;
      margin: 0 auto;

The logo will be your gravatar (details below), and this sets the location (via padding and measured in rem units, for more about rem units see this article), shape (via border-radius which defines the circularity, if you will, of the image), size (via width), and again location (via margin). Now that we’ve done some setup, we can move on to the gravatar logo.


First, we will set up a gravatar. Go to Gravatar’s site and set up an account, if you don’t have one already. Upload the image you wish to use, and follow all the instructions for setting up your gravatar. Eventually, you will be given an email hash, and you should add this to your _config.yml file, something like this (with other identifiers removed):

    gravatar_md5:     //your hash here

Then open up your sidebar HTML file and add this line right inside the first div:

 <div class="sidebar-logo" style="align:center">
      <img src="{{ }}?s=120" />

This will allow the CSS to be applied to your gravatar properly.

Contact List

Below the logo, we have some stylish icons that link to various methods of contacting me. These icons are from the excellent (and free) Font Awesome icon pack, and are a breeze to install. The easiest way is to use their Bootstrap CDN: all you have to do is add the following line to your _includes/head.html with your other CSS links:

<link rel="stylesheet" href="//">

Now you have access to the icons, but how do you use them? I will show you some example code below, which works with your _config.yml file, but first take a look at the 519 icons included in the Font Awesome pack. Chances are you’ll find some that you like better than the ones I use, or you’ll find one for a social media account that I don’t have linked, but that you do.

On to the code: the first thing you’ll want to do is set up a div container for your contact list, like so:

<div id="contact-list" style="text-align:center">
<!-- contact icons go here --> 

You will want one of these div containers for each row of icons you want to use. Within these, you will add an if block that will display an icon and link if you have specified the site in your config.

In the example below, your config is checked to see if you have defined an attribute named github under author, and if it is present a link to github is constructed with your github username (assuming that’s what the github attribute is set to). Within that a tag is a span tag with a class attribute that tells it to stack the images within. We are stacking icons to allow for a border, which is defined by the first i tag and the enclosed icon in the second i tag. For more examples on what you can do with the Font Awesome CSS, see their examples page.

{% if %}
  <a href="{{ }}">
    <span class="fa-stack fa-lg">
      <i class="fa fa-square-o fa-stack-2x"></i>
      <i class="fa fa-github-alt fa-stack-1x"></i>
{% endif %}

Your actual link will be different based on the contact method: LinkedIn will have a different way to get to a given profile than Github, as an example, and if you want to include an email you will instead have a mailto: link. Repeat this pattern (or one that you make with Font Awesome’s many styling features) for each icon you want on each row, and don’t forget that each row will have its own contact-list div!

Description and Navigation

These items are mostly unchanged from the original Lanyon sidebar, however I did remove the download link because it is mostly redundant with the link to the project and it doesn’t work if you are primarily working on the master branch. If you do want the download link, change this:

<a class="sidebar-nav-item" href="{{ site.github.repo }}/archive/">Download</a>

to this:

<a class="sidebar-nav-item" href="{{ site.github.repo }}/archive/">Download</a>


Lanyon comes with a generated RSS file, atom.xml. All you have left to do is link to it where necessary. As an example, I have added a link to the RSS feed on the second row of the contact list.

Closing Notes

I hope this gives a little insight into the use of Jekyll, Poole, and Lanyon in bootstrapping and customizing a personal site on Github Pages. For further reading, please refer to the links at the top of this post.

Setting Up an Elegant Blog with Github Pages, Jekyll, and Poole; Part I

Recently, as an extension of my note-taking obsession, I decided to start this blog, primarily to share what I’ve learned the hard way. I already had my domain name registered via Namecheap (non-ref), so it was time to find hosting. Luckily, Github offers free hosting with support for Jekyll. Jekyll is a Ruby-based static site generator that authoring easy by automatically building Markdown files, but remains powerful enough to create all sorts of site customizations.

In this tutorial, I will walk you through the steps I took and the resources I used to build this blog, the first undertaking of its kind for me. There were many tools that made setup easy, but it was still enough work that it was a fun and enlightening process.

To begin with Github pages, you will have to create a repo on Github entitled This will be your URL if you don’t register a custom domain, but having your own domain is always nice. It takes just a few extra steps, but is worth it for the professional look it offers your site.

Setting Up Poole

The first step is to get Poole. This site uses the minimalist Lanyon theme, which keeps navigation in a collapsible sidebar. Poole on its own is described as a butler for Jekyll, which is really a great analogy: it provides a vanilla install of Jekyll, setting up many of the folders that Jekyll will use to generate your site. Follow the instructions at the Poole website to install the gemfile, then clone down the empty repository you made, go to the repo for the theme you want and download the provided archive. Extract that to your local repo and push it to your remote, and you’re all set with Poole!

Setting Up a Custom URL

Github offers two sets of instructions for setting up your domain depending on whether you are using an apex domain or subdomain. To set up the appropriate records with Namecheap specifically, navigate to the Manage Domains page, select the domain you wish to set the record for, and click the ‘Edit Selected’ button. Now, on the left navigation pane, click the ‘All Host Records’ link. On this page, you will need to set two A records for hostname @, one to and the other You will also need to set a CNAME record for hostname www to your Github Pages URL (in my case

When you have done this, all that is left is to edit the CNAME file (a blank one comes with Poole) to have your custom URL. Save the file and push it to your remote, and navigating to your blog via a custom URL should work shortly.

Setting Up Your Configuration

The main way to do basic configuration on your site is to edit your _config.yml file in the root of your repo. Here, you can set the markdown engine, code highlighting engine, and more. These will allow you to leverage the liquid templating system and customize the sidebar later. For an example _config.yml file, see my config.

Setting Up Your About Page

Poole comes with an example page that gives you a general idea of how to leverage Markdown for the content of your page. What you will also notice is some information at the top of the page. This is the YAML frontmatter, and gives Jekyll some important information about your page (or post) that it will use when generating your site. Here is the default frontmatter in

layout: page
title: About

Layout specifies which specific layout to use (they are located in your _layouts folder), in this case we are using a page layout, as opposed to a post layout. We can also specify the title. I didn’t make any additional changes to the frontmatter here, the frontmatter is much more powerful (and useful) in the context of a blog post.

Open up your local in your favorite text editor if you haven’t already, and write something up! Now, I’m sure you don’t want to push every minor change to Github just to preview your changes, so instead of that fire up your Terminal and run jekyll serve. This will allow you to access your generated website at localhost:4000 and will rebuild your site when any file is changed so that you can quickly view any edits you make before publishing. Play around, and when you’re satisfied with your page, push it to your remote repo.

Setting Up Your First Post

The primary difference between a post and a page is the location of a post (they will be put in your _posts folder) and the filename, which will be the date followed by the title, e.g. (for my excellent previous post). You can also take advantage of more YAML variables here, such as tags and category. Go ahead and write an introductory post and give it some tags! To preview your post, fire up your terminal, navigate to your local repo for the site, and run jekyll serve. Like above, this command will build and serve your site, allowing you to view it at localhost:4000. When you want to publish (you can go ahead and publish what you’ve written now, or write another post later), use git to add your files to the staging area, commit them, and then push them to your remote repo.

Setting Up Drafts and .gitignore

Another handy feature is the ability to save drafts. Instead of saving a dated markdown file to the _posts folder, save an undated markdown file (e.g. to the _drafts folder. In order to preview, run jekyll serve --drafts. When you are ready to publish the post, rename it according to the convention above and move it to your _posts folder.

Before you push anything to your remote (and public) Github repo, it may be wise to create a .gitignore file. Like the filename says, this file tells git which files to ignore so that they don’t show up in your public repo. Simply add the name of a specific file or files (by using asterisks as wildcards) to its own line. For a template, feel free to refer to my own .gitignore file. The most important thing for me was to not share my _drafts folder, so that I could both keep my commits clean (and not have dozens of draft edits being pushed along with a major page overhaul) and to keep post ideas private until they are finished, polished, and ready for the world to see. Read more about .gitignore here.

That is it for part 1 of this guide, please check back again soon for Part 2, where I will cover more customizations and other blogs that helped me set mine up.

Sublime Markdown

I take a lot of notes. Obsessively. Any time I’m writing code, I’m also writing prose: documenting every train of thought, code snippet, and the structure of the program I’m working on. For me, it’s almost a form of cartography, mapping both my mind and the code. Originally, I did this all in Notepad in Windows and nano in Ubuntu. This left much to be desired: I couldn’t easily show dead-end paths, Notepad is just ugly, displaying code snippets was clunky, and other small annoyances piled up constantly over time. Enter Sublime Text.

The Editor

Sublime Text is a powerful, highly extensible, and beautiful text editor available for Windows, OSX, and all flavors of Linux. Powerful on its own, its usefulness is multiplied by the plugins available to it. There are two versions available, ST2 and ST3, the latter of which is in beta. Sublime on its own didn’t solve all the problems I was having with my note-taking, but this is where its extensibility comes into play. There is rich support (via plugins) for Markdown, which is a great way to introduce structure and rich content to your notes, while providing the ease of use of using a plaintext editor. Starting this site (which uses Markdown built by Jekyll to format posts) really got me excited about using Markdown in my everyday work, despite having used forms of it for quite some time on Reddit and Github both.

The Plugins

  • Package Control - The Sublime Text package manager, which is the most convenient way to install plugins. Simply copy the python script appropriate to your version of Sublime Text. To do this, open Sublime Text and press Ctrl + ` to open the built-in python console. Paste the script and press Enter to run it. You can now access Package Control with Ctrl + Shift + P.

  • Markdown Editing - The main Markdown editing plugin, this provides syntax highlighting, autoclosure of special characters like `, _, and *, a bevy of keyboard shortcuts, and much more. It supports Markdown, Github-Flavored Markdown (my personal preference), and MultiMarkdown as well.

  • SmartMarkdown - This enables even more keyboard shortcuts to make you more productive if you’re the memorizing type, along with headline folding and unfolding.

  • Markdown Preview - Markdown Preview, true to its name, allows you to preview your Markdown built as an HTML file, and can also save your built HTML file. This is especially useful for your notes, and less necessary if you are using markdown for software like Jekyll which automatically builds your markdown file. You can use either Python Markdown or the Github Markdown API to build your files.

The Installation

Thanks to Sublime Text’s excellent Package Control installing these plugins is a breeze. Launch Package control with Ctrl + Shift + P and type ‘Install Package’ and then Enter. Now start typing the plugin name you wish to install, Enter again, and that’s it! Repeat this process for each plugin you wish to install.

Package Control in Sublime Text

The Customization

Sublime Text is already a beautiful editor, but there is a rich environment of themes and color schemes available for your tinkering. Across all my installations, I like to use Monokai Extended for the Monokai-Bright color scheme. Install this as you would any other plugin. On Windows, I prefer the default Sublime Text theme, but on Linux I like to use the Soda Dark theme.

The Configuration

To configure Sublime Text and your extensions, simply go to Preferences > Settings - User (for Sublime) or Preferences > Package Settings (for your plugins) and then pick the package you wish to configure. All settings files are in JSON, and the default settings (which you should never edit, as these will get overwritten with every update) show you all the options you have for configuration. Below are examples from my own configuration:

Sublime Settings:

    "theme": "Soda Dark 3.sublime-theme",
    "font_face": "ubuntu mono", 
    "font_size": 11,
    "tab_size": 4, 
    "translate_tabs_to_spaces": true

Note: These are only additions. You may have other settings set here by previously installed plugins.

MarkdownEditing Settings:

    "color_scheme": "Packages/Monokai Extended/Monokai Extended Bright.tmTheme",
    "line_numbers": true

The color_scheme setting overrides the themes that come with MarkdownEditing.

Markdown Preview:

    "parser": "github", 
    "enable_uml": true 

The parser setting forces the Markdown Preview parser to use the Github API for markdown parsing, enabling extra features.

The Other Plugins

  • GitGutter - This allows you to see changes to the file you are working on in the gutter as compared to the file on on git. You can configure it to compare against HEAD (default behavior), or a particular branch, tag, or commit.

  • SublimeCodeIntel - SublimeCodeIntel brings code autocomplete for a number of languages to Sublime Text.

And that’s it! Happy note-taking, blog-building, app-building, and everything else you’re now using Sublime Text for!

A Short Introduction

This site is hosted on Github Pages and built using jekyll with the lanyon theme. My plan for this site is to serve as a hub to view my projects, social media profiles, and, most importantly, to share what I’ve learned from implementing various projects. My hope with this blog is that it will help others who have run into similar roadblocks to think about a way around (or through) them. I will be implementing more features as time goes on, and in a future post I will share how this site was set up and customized.