Creating a Blog

I was recently inspired by my friend to create a blog. After thinking, “I’ll get around to that when I have time” for many months I decided to just go for it.

It actually took me almost 2 whole days to fight with different platforms and figure out how hosting on Github works but it turns out it is really simple if you know where to start.

For my friend, others, (and frankly myself so I don’t forget) I want to explain “How It’s Made”

Github Account

First, you’ll need to join Github. Note that, unless you want to pay for a domain name, your website URL will be <username>.github.io so choose your username wisely.

Next, create a repository called <username>.github.io where <username> is the user name you chose to create your account.

Jekyll-Bootstrap

I decided to use Jekyll-Bootstrap because I wanted to get something up and working quickly. The website boasts “0 to Blog in 3 Minutes” and that is pretty accurate (at least if you have the dependencies installed). See their nice quick start guide.

These instructions will tell you how to clone the existing repository into a local repository and then link that with the repository you already created on Github. They also explain how to install jekyll locally, which is important so that you can preview your website content before pushing to Github (which will automagically publish it to your site).

You’ll need to have gem installed first and you can install rake to follow the examples in the quick start guide.

$ gem install jekyll

Helpful Guides

To supplement the Jekyll documentation, I followed the wise advice of others who created their blogs and subsequently blogged about it.

I especially found these posts helpful:

Syntax Highlighting

I spent a while trying to get syntax highlighting to work (I’m not familar with web-dev, css files, etc.). In the end, I did this:

  1. Added Jason Fisher’s syntax.css to <username>.github.io/assets/themes/twitter-2.0/css/
  2. Added the last line of the following code to <username>.github.io/_includes/themes/twitter-2.0/default.html
<link href="/css/bootstrap-responsive.min.css" rel="stylesheet">
<link href="/css/style.css?body=1" rel="stylesheet" type="text/css" media="all">
<link href="/assets/themes/twitter-2.0/css/syntax.css" rel="stylesheet" type="text/css">

Publishing a post

Once you’re all set up, publishing a post could not be simpler!

Just create a markdown file, add it, commit, and push to Github.

git add <files>
git commit -a
git push

My .gitignore file looks like this which is pretty standard because you don’t actually want to push the _site folder (Github handles creating this for you from the contents in the other directories)

# Temporary Files
*~
*\#

_site/*
_theme_packages/*

Thumbs.db
.DS_Store

!.gitkeep

.rbenv-version
.rvmrc

Working with R Markdown

In order to convert R Markdown files to plain markdown (but get syntax highlighting) I used the convertRMarkdown function written by Jason Bryer and described in this post under Approach Two.

But to get syntax highlighting, I modified the function to call render_jekyll instead of render_markdown.

render_jekyll(highlight="pygments")

This will automatically add the liquid tags necessary to tell Jekyll how to highlight code.