Jekyll - 101

Get Jekyll set up and start writing your first post in no time

Let's start this blog with a bit of inside on how to get started with Jekyll and host it for free with github pages. Jekyll seems like the perfect alternative to a heavier blog engine like wordpress. If you just want to write and maintain your blog in a minimal style worpdress can be overwhelming.


Jekyll is a static site generator widely used amongst developer, designer or anybody just wiling to write from a simple editor like Sublime or Atom. Jekyll uses Markdown syntax to format the post into HTML. It is pretty lightweight, easy to use but the best thing about Jekyll is that it can be hosted with Github pages for free. Jekyll has a very comprehensive documentation to get you started in no time. To start exploring how Jekyll works just run the following commands. The easiest way to start your blog is to fork an existing repository. I had a look around a made a list of the best templates available.

Here are my top 10 jekyll themes/repos:

This blog is based on Clean Blog with a simple side-bar . I wanted a website based on Bootstrap so I could keep on adding on top of a responsive framework I am familiar with.

Once you have chosen a blog template you can run it localy, customize it, write your posts and push everything out to your github repo to be published. I'll be writing a follow up to this post about the ways to host your blog on github pages and configure your own domain name.

Jekyll structure:

This is the basic Jekyll layout

├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.textile
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-
|   └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _data
|   └── members.yml
├── _site
└── index.html

The _config.yml file contains some general settings about your page

title: Christophe Estanol - Blog
email: [email protected]
description: "Write your site description here."
baseurl: ""
url: ""
twitter_username: chrisestanol
github_username:  chrisestanol

The folders _includes and _layouts contain the building blocks of your blog. You can create multiples layouts using Liquid templating engine. The _drafts and _posts folders hold your creative work to be released to the world. When you run Jekyll the _site folder is created which contains all of your HTML nicely formated. You can add to this structure any folder you may need like css, js, img as well as additional static pages about.html, contact.html etc.

Front Mater

title: YAML Front Matter
description: A very simple way to add structured data to a page.

Jekyll uses YAML Front Matter to add structured data like variables or any particular layout to a page. The variables can be created and then used within the page using Liquid.

layout:     post
title:      "Dinosaurs are extinct today"
subtitle:   "because they lacked opposable thumbs and the brainpower to build a space program."
date:       2014-06-10 12:00:00
author:     "Dr. Jekyll"

<div class="post-heading">
  <h1>{{ page.title }}</h1>
  {% if page.subtitle %}
  <h2 class="subheading">{{ page.subtitle }}</h2>
  {% endif %}
  <span class="meta">{{ | date: "%B %-d, %Y" }} </span>

By the way to publish the above code within your post so that Jekyll doesn't render the liquid part like {{ page.title }} you need to surround it with a {% raw %} tag.


There are multiple free or inexpensive ways to write Markdown. The main text editiors for coding, web development like Sublime text, Atom or Textmate all support markdown syntax. You can use one of many online editor like Dillinger, Stackedit, or Markable. Or install a distraction free desktop application like Ia Writer or Mou. I have been using Mou to start writing and I like the viewer and funky themes.

Publish your Post

So now that you know a little more about Jekyll and markdown let's get writing. In your _post folder just create a markdown file. Markdown extensions can vary but the most supported are .markdown, .md, .mkd, .mkdn. So you can use any of these and name your file with the following syntax:


And you're ready to push it to github and have your first blog post published. Happy writing everyone!

comments powered by Disqus