How To Use Jekyll Part-2

Created by Phil Thompson

This is part 2 of my introduction tutorial to jekyll. In this part I’m going to dig into the power of the blog with jekyll.

If you haven’t seen part 1 of this tutorial yet you can see it here How To Use Jekyll Part-1

So moving on. If you tried to make a blog just using html files you can know how much of a nightmare it can be, with having to copy a html file then changing the post content then sorting out the file so there is no conflicts with the name of the post etc. Then you get it uploaded and realise that you forgot to put a link to it in your main blog section etc etc etc. Yes it would be a nightmare.

Where jekyll comes in is that it takes away about 80% of the work once you have it all set-up, leaving you to focus on what counts and that is the post content.

Now you might be thinking “Well why not just use wordpress that’s what it’s for”. Granted wordpress is an amazing peace of software don’t get me wrong. I have most of my clients using wordpress as a CMS for there site and I have used it for years, but that doesn’t mean that it’s not without it’s problems. For example if you don’t have an internet connection then you can’t work on your site content and see how it will look. Just because of the way you develop with jekyll you can fully work offline and then just deploy your site as soon as you have a connection.

Anyway lets get on with building the blog section of the site.

First you need to create a couple of files. In the _layouts folder add an html file called post.html. Then go to the root level and create a couple of folders, one called _posts and one called blog, then finally inside the blog folder create a index.html file.

Add These Files

This is the files you need for a basic blog. Lets now open the default.html file and add a link so people can get to the blog which will be at /blog/. Now if you open the index.html file that is inside the blog folder.

Then at the top of the file we need to put the yaml mark-up in our case we are going to use the default layout for this blog.

  
    −−−
    layout: default
    title: blog
    −−−
  

Then we are going to place the main layout content for listing all the blog posts on the page as well put in a for loop to tell jekyll to list all of the blog posts. I’m going to place all the posts in an unordered list.

  
    −−−
    layout: default
    title: Blog
    −−−
    <ul>
     for post in site.posts 
    <li>
      <a href=" post.url ">
        <h2> post.title </h2>
        <p>
           post.content 
        </p>
      </a>
    </li>
     endfor 
  </ul>
  

Lets briefly run you through what the tags are doing in this page. for post in site.posts and endfor is your for loop. What this is doing is looking inside your _posts folder for all of your posts and everytime it finds one it will spit out this html code for each post. Then the post.url pulls the url for the post, post.title gets the title of your blog post and finally post.content pulls the content of the blog post.

Their is a plugin for jekyll that will add a couple of tags so instead of displaying your full post you can just display an excerpt from the post.

Now we have this page set-up lets make a template that will be used to display the full post to your visitors can read it.

Open the post.html file that you have in your _layouts folder. To keep this simple we are going to use yaml to call the default template and the content of this page will just be some code to load the blog post.

  
    −−−
    layout: default
    −−−
    <p>Created by <span class="fn">Phil Thompson</span></p>
     content 
  

That is all you need to put in this template for now. You can always add more if you want to.

Now finally lets create your first post.

Go to the _posts folder and create a file. The name of the file is important and you need to follow a naming convention which is date-name-of-post in the form of YYYY-MM-DD-name-of-post then it can be either a html file or a markdown file. So lets say that you created a post on the 28th February 2013 called hello world and wrote it in markdown then the file would be called 2013-02-28-hello-world.md then open the file.

Then the yaml mark-up at the top of the file will be a little different to what you normally put there. Here is the most basic information you can put in there.

  
    −−−
    layout: post
    type: post
    title: Hello World
    −−−
  

and then you place your post content.

  
    −−−
    layout: post
    type: post
    title: Hello World
    −−−
    <p>Hello World this is my first blog post</p>
  

Save all of the files then open your ruby terminal and run jekyll −−server

When you do this you will see that inside your _site there will be a couple of new files.

Created Files

Now if you open your browser and go to localhost:4000 you will see your site and be able to go to your blog and view your first post. To add more posts now all you will need to do is just create a new file in the _posts folder and follow the same naming convention and place the same yaml mark-up at the top just with a different title then write your post and that is it, jekyll will add a link to your post on the blog page and compile the full page mark-up for your new post simples.

Anyway that’s it for this tutorial keep an eye out for part 3 where I will introduce you to adding categories and showing you a RSS feed generator plugin and well as a sitemap generator which will produce a sitemap that looks like this www.bhsowebdesign.com/sitemap.xml. In the mean time have fun playing with jekyll and don’t be afraid to experiment with putting things in the yaml mark-up and in a way inventing your own tags to display what you have put there.

If you have any problems you can always leave a comment or send us a tweet and I will see what I can do to help.

comments powered by Disqus