Kyle Stratis Software Developer in Tallahassee, FL

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 yourname.github.io. 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 192.30.252.153 and the other 192.30.252.154. You will also need to set a CNAME record for hostname www to your Github Pages URL (in my case kylestratis.github.io).

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 about.md 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 about.md:

---
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 about.md 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. 2015-04-06-sublime-markdown.md (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. ruby-blog-first-draft.md) 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.