How To Use Jekyll Part-1

Created by Phil Thompson

Jekyll isn’t the hardest set-up to use and yes do need to use the terminal but not too much so don’t be scared.

Lets get started on how to set-up and use jekyll.

Go to www.rubyinstaller.org/downloads to get the super simple to use ruby installer, you will also need the ruby dev kit which you can get from the same address.

RubyInstaller.org Download Page

Once you have both ruby and the dev kit installed you need to run the gem install command to get jekyll.

Run gem install jekyll

Now you have set-up the basics that you will need.

Next you need to create the folder that you want to use to develop you site in locally (for this tutorial we will call the folder mySite).

Inside mySite you will need to set-up the following files.

Directory Tree

Just to quickly explain the folders the _layouts folder is where you will put all of your templates for your site. So far we have put one in there that we are calling the default template. The templates are referred to by using the files name so default.html is the template called default if you had a blog.html then that template would be called blog nice and simple see.

We also have here the css, js and images for the site.

Then finally we have the index.html which will contain the content for the home page of the site, but more about that in a moment.

This is all the basics set-up so lets move on to the default template.

Open the default.html file and add the following code.


<html>
  <head>
    <title> page.title </title>
    <link rel="stylesheet" type="text/css" href="/css/style/css">
  </head>
  <body>
     content 
    <script src="/js/scripts.js"></script>
  </body>
</html>

You will notice the special tags in there of page.title & content . These are special tags for jekyll which is know as liquid mark-up template language. What these tags do is tell jekyll where to put certain peace’s of content. These two do the page title and the main page content respectively. This file would also be the best place to put your navigation and any other shared content like any page wrappers or a sidebar that you might have across your site.

Now lets go to the index.html file and create the content for the home page.


<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum adipisicing ea sit do. </p>
<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum in aliquip sit minim exercitation nostrud in aute mollit Ut nostrud sit incididunt ex sit in dolor sed Duis culpa id aliquip exercitation elit ad amet laborum occaecat id mollit cillum laborum Ut in minim laboris quis laboris cillum laborum laboris laboris laborum. </p>

Now just putting this in the index.html file won’t work because jekyll doesn’t know what template to use to produce this page and it also doesn’t know what the page title is.

To do this we need to put some yaml mark-up at the beginning of the file. Here is an example of how to tell it to use the default template and give it the page title of home


−−−
layout: default
title: Home
−−−
<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum adipisicing ea sit do. </p>
<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum in aliquip sit minim exercitation nostrud in aute mollit Ut nostrud sit incididunt ex sit in dolor sed Duis culpa id aliquip exercitation elit ad amet laborum occaecat id mollit cillum laborum Ut in minim laboris quis laboris cillum laborum laboris laboris laborum. </p>

It is important that the yaml mark-up has −−− before and after it otherwise it won’t work.

Now save all of your files and open your ruby terminal, cd to your project folder then type in your ruby terminal jekyll −−server

Run Commands

When you first run it you will get an error but ignore it.

Error Message

As long as you see the success line bellow you are all good.

Success Message

You will see that jekyll has created another folder in your project call _site.

New Folder Created

This is where your rendered site code is.

Now go to your browser and go to localhost:4000 and you will see your site.

localhost:4000

To check it has worked properly view the source of the page in your browser and you should see all of your html mark-up in the file.

localhost:4000 Source

That’s it you have created your first page with jekyll (pat yourself on the back lol).

Now lets add a second page.

In the code for the default template I’m going to add a little bit of navigation.


<nav>
  <a href="/">Home</a>
  <a href="/about/">About</a>
</nav>

If you notice I’ve pointed the link to the about page as a folder and not an html file. This is because it will generate a form of user friendly permalinks so the url will be www.mydomain.com/about/ instead of the other option which would be www.mydomain.com/about.html

Now lets create the second page what you need to do is create a folder called about and place an index.html file inside it.

Created The About Page

Then open the about/index.html file and do the same as you did for the first page at the top of the file.


−−−
layout: default
title: About
−−−

Then add the content for the page.


−−−
layout: default
title: About
−−−
<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum adipisicing ea sit do. </p>
<p>Lorem ipsum proident adipisicing tempor aute pariatur dolor reprehenderit in culpa voluptate proident do et reprehenderit in in exercitation ut ex labore in nisi. </p>
<p>Lorem ipsum in aliquip sit minim exercitation nostrud in aute mollit Ut nostrud sit incididunt ex sit in dolor sed Duis culpa id aliquip exercitation elit ad amet laborum occaecat id mollit cillum laborum Ut in minim laboris quis laboris cillum laborum laboris laboris laborum. </p>

Then run the jekyll −−server command again and the second page will be created by jekyll and that’s how simple it is.

To deploy your site all you need to do is ftp to your server and copy the contents of the _site folder and that’s it.

Keep an eye out for my next tutorial where I will take you through the blog and post side of jekyll.

comments powered by Disqus