Getting Started With Jekyll on Github Pages

Feb 26, 2014
TAGS:   #tutorial


Introduction

What is Jekyll? Jekyll is a blog-aware, static site generator in Ruby. It is commonly used by GitHub users to write small blogs or to display their hacks. This blog, by the way, is also generated by Jekyll.

Firstly, I’d like to clarify what this little post is about. It won’t teach you Jekyll, it’ll just help you set up your username.github.io on Jekyll. If you want to learn more about it, check out the repo on GitHub or visit the homepage.

Now, many people are confused as to where one gets started. Here’s what you can do (the Jekyll website mentions this too):

~ $ gem install jekyll

This installs jekyll.

~ $ jekyll new my-awesome-site

This gives you a good started template.

To have your first website up nd running, simply go to the my-awesome-site folder and on your terminal run:

~ $ jekyll serve

And that’s it! We’ll talk more about this in the upcoming sections.


Basics (If you do not want to follow a template)

So here are the brief steps you need to follow to create your blog/hack page on Github pages:

  • First, create a repo with the name username.github.io, where username is your username.
  • Next, create a file with the name _config.yml. This is a file that contains all the configuration variables for your site in the YAML format. You can use any text editor for this (I prefer Sublime Text 3). Now put the following content in your file:

      markdown: rdiscount
      permalink: /:title
      pygments: true
      auto: true
      rdiscount:
      extensions: [smart]
    

    and save it and push it in the main repo.

  • Create a directory and name it _layouts. As is apparent from the name, this folder stores the layout files for your site. Here, you can put your HTML files and these will be used when you post. I use a (more or less) uniform layout for my site and it is stored under the name of normal.html. You can have a look.
  • Next, you’ll need to create a _posts folder. This is where your main content will go. Make this in the parent directory. The files you add here will have the format yyyy-mm-dd-title-here.markdown where yyyy-mm-dd is the date of publishing, title-here is the part of your url and markdown is the file extension (of course!).
  • There is also an _includes folder which you won’t require as of now (since we are talking about a very basic site here).

So here’s what your directory structure looks as of now:

.
├── _config.yml
├── _includes
├── _layouts
|   ├── normal.html
|   └── blog.html
├── _posts
|   ├── 1970-01-01-the-first-date.markdown
|   └── 1995-02-20-some-random-blogpost.markdown
└── index.html

And you are done! Now, I’ll tell you a little about the format of the above files.


index.html

Here’s what your landing page would look like:

---
layout: normal
title: My Homepage
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

And that’s it! Yes! This will take the format of your default page that you would create in the _layouts folder. As simple as that.


A Random Page

A page on your site would behave in a way no different from index.html, but here are a few quirks you can add to it.

  • Post Loops: If you have multiple posts on your site (which you will) you will want to show them in a uniform manner. Here’s how you can do so (paste the following in the content):

      {% for post in site.posts %}
          <h2>
            <a href="{{ post.url }}">{{ post.title }}</a>
          </h2>
      {% endfor %}
    
  • Categories and Multiple Blogs: If you want more than one blogs on your site, add a category:<categoryname> to the attributes of your posts (the space in between the two ---’s) and the following in your post loops:

      {% if post.categories contains '<categoryname>' %}
        content
      {% endif %}
    

    such that the net content looks like this:

      {% for post in site.posts %}
      {% if post.categories contains '<categoryname>' %}
          <h2>
            <a href="{{ post.url }}">{{ post.title }}</a>
          </h2>
      {% endif %}
      {% endfor %}
    

There’s a lot of stuff that you can do with your pages, but as I said, this is the basic setup, so you should be fine with this for now.


A Sample Post

Here’s how a blog post should look like:

---
layout: blog
title: "My Hello World Blog!"
category: blog
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

After writing the above markdown and save it as 2014-02-26-my-hello-world-blog.markdown and push it into _posts folder. And lo and behold! It’ll render as a static HTML page.


< Back