get in touch w/ IT via woowie

Easy blogging with jekyll and github

In this post I will show you an easy way to express your thoughts via the static site and blog motor Jekyll. We will host our blog on github pages for free! To set up a starter skeleton project only takes a few minutes.

Preface

My story started ~6 years ago, when I first wanted to do some "blogging". On the early days I used some really simple and free blogging motors, like blogspot and others what I can hardly remember their names. Later, I started a blog about my sports life. It was like a diary of mine on the net around the topic of the gym. It was sufficient for my solely purpose. Then, after a few years I wanted to start a semi-personal blog about technology and stuff. I wanted to archive my findings about the Unix world somewhere and save some snippets about programming. I started to use Wordpress, but I was overly unsatisfied with it. It was such a pain in the ass to create a new blog post, it was time consuming and I couldn't insert code snippets properly in it. Also, when I wanted to modify my blog on the slightest level Wordpress made it nearly impossible for me. I wanted something, what is

  • Simple ~easy to use
  • Free
  • Can use code snippets with syntax highlighting

Finally, I've found GitHub pages which runs Jekyll on it. So, I started to use Jekyll for static site blogging and it's awesome, belive me :)

About Jekyll

So what is Jekyll? The original website of Jekyll's is very good and descriptive. So, everything I write down here is just a shortcut of the information what can be found on the general Jekyll website. http://jekyllrb.com/ I advise it very much to read it properly. It's not so long and it is concise. Otherwise, read my blog post for a summary.

Jekyll is a simple, blog-aware, static site generator.

Here it is, that simple. Jekyll is just a tool to create web friendly content out of text files. Usually from markdown + html + some config files. The idea is simple, let the user write some templates, let the user also write blog posts in simple text format (textile, markdown, etc), and let the framework do the magic which means, creating static html content from the text files and the output of the process is ready to deploy into a webserver. Hint: the hosting will be done by GitHub.

An optional work flow

When our blog is ready we will publish new articles as follows:

  1. Open the sublime project of our blog
  2. Hit CTRL+K; CTRL+P -> this will create a new post with the datas needed by jekyll
  3. Finish writing the post
  4. Commit the changes into our CVS (our CVS will be git) and we will push the new post to github with it -> Publish
  5. Our new post will be available in an instant

The whole process is faster, more elegant and IMHO the output is prettier than it was when I used Wordpress for blogging. : *[IMHO]: In my honest opinion

Prerequisites

  1. You need a github account first. Visit https://github.com/ and create a free account.
  2. On GitHub, create a new repository called <your_username>.github.io
  3. You will need nodejs, ruby, bundler and jekyll on your system. Install node, ruby and jekyll via apt on *buntu systems, and bundler via gem which comes with ruby. Gem is a package manager for ruby.
  4. Later on, you will most probably need python as well, for syntax highlighting. But we will skip that now.

After install, I have these versions of those on my system

$ node --version
v0.10.34
$ ruby --version
ruby 1.9.3p484 (2013-11-22 revision 43786) [x86_64-linux]
$ jekyll --version
jekyll 2.4.0
$ bundle --version
Bundler version 1.7.9

Scaffolding

Okay, so, after installing the dependencies, we are ready to create our blog. We will start with generating a jekyll skeleton site. Since we will sooner or later push this blog on GitHub, it's time to clone the repo we created on GH.

$ git clone https://github.com/s1ngul4rity/s1ngul4rity.github.io.git
Cloning into 's1ngul4rity.github.io'...
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
Checking connectivity... done.

This command creates a folder named s1ngul4rity.github.io/, we will scaffold our blog into the root of this directory.

$ cd s1ngul4rity.github.io/
$ jekyll new temp
New jekyll site installed in /home/jim-y/tmp/s1ngul4rity.github.io/temp. 
$ cp -R temp/* .
$ rm -rf temp/

Now, our repo root contains some documents generated by jekyll. The generated skeleton app is ready to run, so first, before introducing the jekyll "framework" let's have a look at the skeleton app. In the root directory of our blog (s1ngul4rity.github.io/) bootstrap it by

$ jekyll serve
Configuration file: /home/jim-y/tmp/s1ngul4rity.github.io/_config.yml
            Source: /home/jim-y/tmp/s1ngul4rity.github.io
       Destination: /home/jim-y/tmp/s1ngul4rity.github.io/_site
      Generating... 
                    done.
 Auto-regeneration: enabled for '/home/jim-y/tmp/s1ngul4rity.github.io'
Configuration file: /home/jim-y/tmp/s1ngul4rity.github.io/_config.yml
    Server address: http://0.0.0.0:4000/
  Server running... press ctrl-c to stop.

The jekyll serve command created a webserver on localhost serving our static files. So point your browser on localhost:4000 and have a look at the application.

So far, so good. Technically speaking, you could end up here, and start publishing your blog to github since it's fully functional now, but I assume, you want to learn some more about jekyll first, and I bet, the skeleton blog's appearance is not sufficient enough :)

Architecture

It's time to inspect the architecture of the created boilerplate.

.
├── about.md
├── _config.yml
├── css
├── feed.xml
├── _includes
├── index.html
├── _layouts
├── _posts
├── README.md
├── _sass
└── _site

index.html

As every decent website, our blog also needs a main page. In jekyll this is index.html. We need to prepend this file (all files) with a YAML Front Matter section which is needed for Jekyll to be able to indentify, that it needs to parse the file upon the build process.

A YAML Front Matter is a section of code on the top of a file, which tells Jekyll that this file needs to be processed. On process we mean traversing the file and processing Liquid templates. Jekyll uses Liquid templating.

about.md and other [.html, .md, .markdown] files in root

A Jekyll blog consists of posts and pages. Posts are .. surprise, surprise .. posts, be fair, the world calls these as articles :D, pages are general static html pages, these will be available as http://localhost:4000/about/. You can make an about page, where you introduce yourself, or you could create a contact page, where you put your online media accounts and addresses.

_config.yml

This is your blog's main config page, where you set up things like baseurl and stuff. More about this later.

_posts

The posts folder contains your articles. The naming of your posts are very strict and concise.

The naming convention of these files is important, and must follow the format: YEAR-MONTH-DAY-title.MARKUP.

The creation of a new post is as simple as creating a new markup file in the ./_posts folder with the required naming conventions.

_(layouts|includes)

_includes is the folder for reusable markups/html. Think of it as the place where you put a header.html segment what needs to be appended on every page of your blog.

_layouts is the folder for your page templates. Usually your posts will have a template as well as your pages and you should have a default template for your main page. These templates should contain Liquid tagsand regular html tags also. You will render content into these templates. E.g the template for your posts is a wrapper around the markdown content what you will write.

_site

_site is a folder which is generated programmatically by jekyll. GitHub will create such files which are inside this folder upon build. If you want to host your blog on your own, you will need to serve up these files on a webserver. We will put this folder into .gitignore.

Every other file

Every other file stays as it is. We usually want some assets in our posts, like images. So we will create a folder for assets.

Creation

In this section, we will be setting up additional things to make our skeleton site unique.

Gemfile

As GitHub pages tutorial says, we need a Gemfile in the root directory. So create it.

$ sublime Gemfile

source 'https://rubygems.org'
gem 'github-pages'

Next add _site folder to .gitignore. If you doesn't have a .gitignore file, create it. Now, before going further take some time and think about the look and feel. Obviously, the basic skeleton is coming with a very basic theme. You would probably change it for something better. Since I suck in CSS I will download a free theme for my blog. :)

Theming

Browse http://www.jekyllthemes.org for a suitable theme. In this tutorial, I will use hyde which is a nice multi color theme from poole. I'm currently using poole's other theme, lanyon on my blog. Setting up a theme is easy, but we need to remove nearly all of the boilerplate what jekyll generated for us recently.

$ pwd
/home/jim-y/tmp/s1ngul4rity.github.io
$ rm -rf *.html *.xml css/ _config.yml _includes/ _layouts/ _sass/ .sass-cache/ _site/

Now, that we have space download the theme and copy over the source files.

$ cd ..
$ git clone https://github.com/poole/hyde.git
$ cd hyde/
$ cp -Rf 404.html about.md atom.xml _config.yml _includes/ index.html _layouts/ public/ ../s1ngul4rity.github.io/

Now, if you have done everything right, you should be able to build your newly themed blog.

$ cd .. && cd s1ngul4rity.github.io/
$ jekyll serve

Syntax highlighting

With the new theme we switched to pygments highlighter from kramdown. The highlighting is good enough, but could be better. Why? Just because we are running a technical blog, and we will be publishing code snippets all the time. So how to add a new highlighter?

It's very simple. Just replace the ./public/css/syntax.css file with another. I use GitHub highlighting so I made these modifications.

$ cd public/css/
$ mv syntax.css syntax.css.old
$ wget https://raw.githubusercontent.com/mojombo/tpw/master/css/syntax.css

Also, we can append line numbers for our gists, but the style of these line numbers are not so good. But we can solve the problem by appending these two lines for syntax.css. Credits

.post > .highlight .lineno {
    color: #ccc;
    display: inline-block;
    padding: 0 5px;
    border-right: 1px solid #ccc;
}
.post > .highlight pre code {
    display: block;
    white-space: pre;
    overflow-x: auto;
    word-wrap: normal;
}

Another solution for code blocks is to insert a GitHub gist into your Article. With Liquid it's simple too. Just write {% gist 8d84463549b5adbc19d3 %} in your post.

Configure socials

With Liquid, and _config.yml, you can insert metadata in your posts/pages. First, rewrite our theme's _config.yml a little bit. As stated at gh-pages, GitHub will insert some metadata information to your site. You can use these datas in your pages. To test it out, let's rewrite ./_includes/sidebar.html to append our twitter account after the description, like

Blabla Welcome here - @twitter_link

So, modify sidebar.html as follows

The pinpoint here is the Liquid directive {{ site.author.url }} and {{ site.author.name }} . These values come from the _config.yml. Now, let's rewrite

<a class="sidebar-nav-item" href="https://github.com/jim-y/jim-y.github.io">GitHub project</a>

that we doesn't get the repo name directly from the config file, instead we will use GitHub's injection as stated here. Mind, that locally it won't work, only when we will host our files on GitHub.

<a class="sidebar-nav-item" href="{{ site.github.repository_url }}">GitHub project</a>

The site.github namespace will be injected upon gh-build. The final config file looks like:

# Dependencies - "fenced_code_blocks" is automatically enabled
markdown: redcarpet
redcarpet:
  extensions: ["no_intra_emphasis", "autolink", "tables", "with_toc_data"]
highlighter: pygments

# Permalinks
permalink: pretty
relative_permalinks: true

# Setup
title: Hyde
tagline: 'Jim-Ys technical blog'
description: 'This blog shows how <b>awesome</b> static site blogging is. Welcome here'
url: https://github.com/s1ngul4rity/s1ngul4rity.github.io
baseurl: /

author:
  name: 'Jim-Y'
  url: https://twitter.com/attilakling

paginate: 5

# Custom vars
version: 0.0.1

Writing posts

As mentioned in the preface, the workflow is rather simple, and elegant. For making it so, I downloaded a Sublime plugin which adds some jekyll functionality to my editor.

Let's create a new post.

  1. $ cd s1ngul4rity.github.io/
  2. sublime .
  3. In sublime, CTRL+K; CTRL+P
  4. Type in a new post name
  5. A new post appeared in the directory you already set up when you installed the jekyll plugin in sublime. It should be your blog's _posts directory.
  6. The front-matter section is prefilled for you, as shown below.
---
layout: post
title: Welcome post
published: True
categories: []
tags: []
---

You can use GitHub Flavored Markdown syntax in your posts.

Deploy

It's time to deploy our blog to GitHub. For this, we need to use the git CVS.

$ git add -A
$ git commit -a -m 'Initial Commit'
[master e0c97e4] Initial Commit
 20 files changed, 1112 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 404.html
 create mode 100644 Gemfile
 create mode 100644 _config.yml
 create mode 100644 _includes/head.html
 create mode 100644 _includes/sidebar.html
 create mode 100644 _layouts/default.html
 create mode 100644 _layouts/page.html
 create mode 100644 _layouts/post.html
 create mode 100644 _posts/2014-12-23-welcome-post.md
 create mode 100644 _posts/2014-12-23-welcome-to-jekyll.markdown
 create mode 100644 about.md
 create mode 100644 atom.xml
 create mode 100644 index.html
 create mode 100644 public/apple-touch-icon-144-precomposed.png
 create mode 100644 public/css/hyde.css
 create mode 100644 public/css/poole.css
 create mode 100644 public/css/syntax.css
 create mode 100644 public/css/syntax.css.old
 create mode 100644 public/favicon.ico
$ git push origin master
Username for 'https://github.com': s1ngul4rity
Password for 'https://s1ngul4rity@github.com': 
Counting objects: 28, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (25/25), done.
Writing objects: 100% (27/27), 11.79 KiB | 0 bytes/s, done.
Total 27 (delta 0), reused 0 (delta 0)
To https://github.com/s1ngul4rity/s1ngul4rity.github.io.git
   194c5e7..e0c97e4  master -> master

That's it, your core jekyll files, except _site/ is pushed to GitHub, and your page should be online after some minutes. Give them some time to bootstrap your site, for me it took ~15-20 mins to became available. The blog will be available at http://s1ngul4rity.github.io/

You can check my uploaded files at https://github.com/s1ngul4rity/s1ngul4rity.github.io

comments powered by Disqus