Jekyll is a great blogging tool if you have the right skills … or are interested in developing those skills. Primarily you need some command line skills and be comfortable with a text editor. Ideally you also need to be comfortable with Git as well.

Aside from the effectively unlimited control you have over your site and content, the major selling feature of Jekyll is that Github provides integrated support for it. This means that you can just create a repository following a couple of rules and Github hosts the Jekyll build as a website. Neat.

So what are the minimum steps to get a Jekyll blog up and running on Github?

The following assumes you are either on Mac OSX or a Linux with Ruby and RubyGems already installed. If you are on Windows … you have my sympathies.

1. Install Jekyll

Jekyll is written in the Ruby programming language and is distributed as a Ruby gem, the de facto package system for Ruby. You install it using the gem install command.

$ sudo gem install jekyll

2. Create new Jekyll site

Once Jekyll is installed you can create your new site using the jekyll new command with the directory path that you want created to hold the site’s files. Think of this as creating a new project.

$ jekyll new mysite

This will create a new directory mysite and put the new files there.

Have a look inside this directory and you will see something like this:

What are all these files?

_config.yml is the main Jekyll configuration file. It contains a bunch of settings that Jekyll uses itself (details) but you can also add your own key/value pairs here to refer to in your templates.

_posts/ contains the blog posts you write as Markdown files. Each file is named with the date and usually the post title. Each file must contain a header block which contains information such as the post title, date published and which layout to format it with. This header is delimited with three hyphens at the beginning and end. All the content after the header is your post content.

_layouts/ contains templates written in a language called Liquid that define the layout of each page on your site. There are three by default, default.html is the common layout for every page, post.html is for blog posts and page.html is for any other page.

If you look in post.html and page.html you will see that they have a header block like the blog post files with a layout defined, default. Layouts have a hierarchical relationship. When Jekyll creates each final page for your site it looks at the content file (eg your post) and checks what layout it specifies. Then it gets that layout file and sticks your (converted to html) markdown content in place of the {{ content }} liquid tag. Then it looks to see if that layout file had another layout defined, and if so it takes everything it has so far (your content and it’s layout) and replaces the {{ content }} tag of that layout. It repeats this process until there are no more ‘parent’ layouts defined.

_includes/ are little tiny templates of parts of a page. If you have elements that occur in multiple different layouts you can put those elements here once and reference them from multiple layouts. The default ones included are for the HTML <head> and navigation and footer elements of each page. You can see these referenced using the liquid include tag, e.g. {% include footer.html %}.

Arguably these could go in the default layout, but what if you wanted to use more than one default layout (ie more than one layout without a parent layout)? Also sometimes it’s convenient to separate these things out for maintenance.

_sass/ & css/ contain the stylesheet files that format the final output in the browser. By default Jekyll uses SASS to generate CSS files. SASS is like CSS but with a few extra bits that make it nicer to work with, and Jekyll turns the SASS .scss files into CSS for the final site. css/ contains the ‘main’ file and _sass/ contains smaller files that are merged into the main one - kind of like the way that the template includes work. If you don’t like SASS and would prefer to use CSS, you can just delete _sass/ but you will have to write your own CSS and replace css/main.scss with it as css/main.css.

index.html is the main page for your site. It is liquid template and by default produces a list of all your blog posts.

feed.xml is the template that produces an RSS feed for your posts. Again also a liquid template.

about.md is the ‘about’ page for your site. It is a markdown file with a YAML header that specifies the ‘page’ layout. Note that the navigation for the default site automatically picks pages up and puts it in the menu.

What’s with the _ directories?

Files and directories that start with _ are considered by Jekyll to be special files not to be copied over the final site. Any file in the your main site directory that doesn’t start with an underscore is automatically copied over into the final site. If it is a text file with a YAML header it will be processed as content to produce an appropriately named output file (like how about.md becomes the about page). So if you want to upload an arbitrary file to your site, like an image, just copy it into this directory with the path that you want it to have on the site.

3. Do a local preview

Jekyll includes a simple web server that can be used to preview your site locally. By default it runs on the local loopback interface on port 4000. To check out the site that Jekyll created run the command jekyll serve. The -w parameter makes Jekyll constantly check for changes to the files and rebuilds the site. This is really handy when working on a new post or tweaking layouts.

$ cd sitename
$ jekyll serve -w

Then go to http://127.0.0.1:4000 in your browser to see what it looks like.

Assuming you haven’t made any changes already, you will see the index page with the list of posts (just one) and if you click on that you will get the page with that post. You will also see the about page in the header and be able to navigate to it. Also the RSS feed. And you will note a lot of placeholder values like the site title etc that you will want to change.

If you have a look in the Jekyll directory now you will see that there is a new _site directory that wasn’t there before. This contains the constructed site which is what you see above. If you weren’t going to use Github to host your site you could just use the jekyll build command to generate this and then copy it to your web server yourself. It can also be informative to look in here to see exactly what gets created from the Jekyll layouts and other files.

4. Basic customizations

To make the site your own with as few changes as possible.

  1. change the site title
  2. update the email address or remove it entirely
  3. update the site description
  4. update or remove twitter and github usernames

To make these changes, edit the _config.yml file and change the appropriate values.

You also comment out lines with a # instead of removing them if you want to make a temporary change.

For example:

# Site settings
title: Unsolicited Rantings
# I don't want people emailing me
# email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
 This is where I go off on various rants about anything at all really.
 Politics, mobile device operating systems, choice of salad dressings.
 All of this and more are valid topics here.  If you don't like it, then
 you can go elsewhere.
baselink: "" # the subpath of your site, e.g. /blog/
link: "http://yourdomain.com" # the base hostname & protocol for your site
twitter_username: unsolicitedrants #
# github_username:  jekyll

# Build settings
markdown: kramdown

Note that making changes to _config.yml are only processed when jekyll serve launches, so if you will need to restart it before those changes are seen. To do this just press ctrl-c in the terminal window, wait for it to exit and run the command again.

And you will have to refresh the page of course. Note that any other changes, like adding or editing a post or editing layouts do not require a restart.

If you get errors when starting the site again, then you probably have syntactical errors in _config.yml.

5. Add your first post

Once you have the site looking a little like it’s yours, you can add your first post. There is already a demo post provided that you will probably want to delete eventually, but it’s worth keeping around for reference for now.

To create new post, just create a new file with the name in the format of YYYY-MM-DD-POST_TITLE.markdown in _posts/ with the appropriate header. The easiest way to do this is to copy the demo post file and rename it.

Open up the new file in an editor:

  1. Update the title
  2. Update the date (the time is optional)
  3. I suggest removing the categories line
  4. Remove all the content after the header block

Now add your content as markdown after the block.

E.g. 2014-09-22-this-is-my-first-post.markdown

---
layout: post
title: "This is my first post"
date: 2014-09-22
---
So this is my first post using Jekyll.

Save the changes to file and (if jekyll serve -w is running) you will notice it displays a messaging stating that it has detected changes and rebuilt the site.

Regenerating: 1 files at 2014-09-07 10:54:50 ...done.

Head back the the browser and refresh the index page and you will see your new post in the list. Click on the link and you will see that post.

7. Images

So how do I add images? Just add the files to the Jekyll directory and (unless you put them in an underscored _ directory) and they will be copied over to the built site with the same path. Then you can just use the markdown image syntax with the appropriate path to include them in your posts.

I generally create an /images/ directory to put image files in, with a posts/ subdirectory and further subdirectories for images for specific posts. But you can organize these however makes sense for you.

8. Update the About page

One thing we skipped over earlier was the ‘about’ page. If you open it up you’ll see that it looks a lot like a post, but it uses the page layout instead of post and that it has a permalink value in the header.

You can edit the markdown content here to describe your site, or yourself or whatever.

So what does permalink do? It sets a specific URL for the page. If you don’t have this value set, the page gets a URL based on the path of the markdown file. So for about.md, it would be /about.html. With the permalink value of /about/ the resulting output is actually /about/index.html.

You can create whatever pages you require just like the about page, or create none at all and delete the about page. Up to you.

You might also ask how these pages get linked from the navigation on the site. Have a look in _includes/header.html and you’ll see the following code which is responsible for this.

<div class="trigger">
    {% for page in site.pages %}
    {% if page.title %}
    <a class="page-link" href="{{ page.url | prepend: site.baseurl }}">
      {{ page.title }}
    </a>
    {% endif %}
    {% endfor %}
</div>

In brief, the site.pages array has the list of all the pages (not posts, just pages) and this loops through them to create the navigation links. If you look at index.html you will see something similar done with site.posts to generate the list of all posts.

Personally I like to create the directory structure for a page and name it index.markdown instead of using permalink and put the images for the page in the same directory.

8. Publish to github

Easy publishing with Github is one of the awesome features of Jekyll. Well it’s easy if you are comfortable with Git and Github. :-) All you need to do is have a Github account, create a repo called USERNAME.github.io where USERNAME is your Github username. Then you push your Jekyll site into it, Github does the build for you, and the site is reachable at http://USERNAME.github.io. If you have your own domain you can configure the site to use that, but I won’t talk about that here.

  1. If you don’t already have a Github account, create one. You only need a free account. Remember that without you own domain your username will be part of the URL of your site.

  2. Create a new repository on Github, named USERNAME.github.io, where USERNAME is your Github username.

  3. Go to your Jekyll directory and setup Git and add all the files that you currently have.

    If the original “Welcome to Jekyll” demo post is still there, you might want to delete that first.

    $ git init
    $ git add .
    $ git commit -m "initial site"
    

    (Experienced Git users will note the Jekyll already created a .gitignore file with _site in it. )

  4. Connect your local repository to your Github.

    $ git remote add origin https://github.com/USERNAME/USERNAME.github.io.git
    

    USERNAME is of course your Github username.

  5. Publish to Github You publish to your Github site by doing a git push to it.

    $ git push -u origin master
    

    You will be prompted for your github username and password at this point. You will have to do this every time until you setup SSH keys which is a post for another time.

    Now go to http://USERNAME.github.io and bask in the glory. ;-)

9. Publishing new posts

Of course now that the site is live you will probably want to add more posts etc. All you do is use git to add, commit, and push the files that you have added or changed.

For example if I had a “second” post, _posts/2014-09-10-second.markdown

$ git add _posts/2014-09-10-second-post.markdown
$ git commit -m "added second post"
$ git push -u origin master

And then

This covered only the very basics of getting started with Jekyll on Github. I haven’t talked about customizing layouts or stylesheets, setting up a domain or SSH keys, tags or categories, post permlinks, custom data on posts, collections, drafts, adding comments with Disqus, publishing to other hosts, or using plugins.

There are plenty of Jekyll resources online and these are topics for another time.

Have fun with Jekyll. Go write something.