français english

Slavisa Jovanovic

Personal web page

How to build your customized blog using Jekyll

Jan 4, 2015

In this tutorial you will learn how to build your own customized blog using jekyll.

First of all, I’m not a web developer and I’m not planing to be in the near future. Only I want is to have an easy-to-use way to post my tutorials on the web. In the past, I used Kompozer to edit my web pages but since I’m a console/terminal guy and I like to write plain text documents (using vim of course), this wasn’t the best solution for my needs. Moreover, I’ve discovered markdown for note taking and its extremely simple syntax (for more details, see official website). I’ve been using markdown syntax on a daily basis especially for note taking and writing drafts before its finalization in latex. What is good to know about markdown is that it is easily to convert a markdown file to a plethora of formats: .html, .tex, .doc, pdf, … using pandoc tool. The best in this story is that Jekyll allows us to write our posts in markdown without thinking about html syntax. That’s great!

I won’t write about how to install jekyll and configure it. For this purpose, you have its official web page. What I’m going to explain is how to personalize the out-of-box jekyll web page.

First of all, I will show you how to change your header and adapt it to your needs. Out-of-box jekyll installation gives you a folder tree structure as one presented bellow (to find out more details about this structure, see jekyll web page):

_config.yml
css
feed.xml
_includes
index.html
_layouts
_posts
_sass
_site

If you have a look into _layouts folder, you’ll find 3 files:

default.html
page.html
post.html

The file we are interested in is the default.html and we’ll see its short content:

<!DOCTYPE html>
<html>

 include head.html 

  <body>

    include header.html 

    <div class="page-content">
      <div class="wrapper">
        <div class="post">

Welcome message

Jan 4, 2015

Welcome to my blog. Here you’ll find very soon some tutorials about HW/SW (co-)design, modelisation, tools configation, linux tips, writing tips, open source, …

int main(int argc, char* argv[]){
cout << "Hello world!" <<endl;
return 0;
}

</div>

      </div>
    </div>

    include footer.html 

  </body>

</html>

We can see that we have all 3 files displayed above that are called in different sections of the default.html page. Whad does it mean? If you want to customize your web page, you need to modify only two files: header.html and footer.html. The header.html will give you the header of your web page whereas footer.html will give you your personalized footer. Let’s start with header file.

Header file

There is a default header file supplied with out-of-the-box jekyll installation. But I’m sure that you won’t like it. All you have to do is to modify it. The header.html file is stored in include folder of your jekyll installation. The content of the header file of my blog is listed bellow:

<div id=titre>
	<div class=lang>
		<a href="/"> français </a>
		<a href="/"> english </a>
	</div>
	<h1 id=h_titre> Slavisa Jovanovic </h1>
	<p class=soustitre> Page web personnelle </p>
</div>

<div class="image">
	<img id="slika" src="/assets/img/hdrpic.jpg">
</div>


<div class=navigator>
	<ul>
		<li>
		<a href="/about/"> About</a>
		</li>
		<li>
		<a href="/news/"> News</a>
		</li>
		<li>
		<a href="/cv/"> CV</a>
		</li>
		<li>
		<a href="/publications/"> Publications</a>
		</li>
		<li>
		<a href="/recherche/"> Recherche</a>
		</li>
		<li>
		<a href="/enseignement/"> Enseignement</a>
		</li>
		<li>
		<a href="/"> Divers</a>
		</li>
	</ul>
</div>

You see that this file is very basic and only you need is a basic knowledge of html syntax to customize it. I had defined 3 div sections: the first one for the title part, the second one is for the image and the third one is the navigator section as a list. You may also notice that I used some id and class for each div section to simplify their customization with the CSS syntax. For the moment, you don’t have to worry about the internal links. We’ll attack this part later. Another remark is about the place where you store the files you’ll call from your web pages. I created a folder assets in the jekyll initial structure and inside this folder 2 sub-folders: img for images and files for files. You can see that the image I use for my header file is stored in /assets/img folder.

The next step is to embellish your header. For this purpose, I use CSS syntax. The jekyll initial structure provides some CSS files. They can be found in the css folder and in _sass folder. We can edit one of these files for this purpose, but for the sake of simplicity, I prefer to add an additional file. The file I created is _header.scss and I put it in the _sass folder. You can see its content.

To allow jekyll to use your style-sheet _header.scss file, you have to add a line into main.scss file. The last section of this file is presented bellow:

.....

// Import partials from `sass_dir` (defaults to `_sass`)
@import
        "base",
        "header", 		<- added line for header
        "layout", 
        "syntax-highlighting",
        "footer" 		<- added line for footer
;

I added the line containing "header" for _header.scss file and another one "footer" for _footer.scss file. This way, the jekyll engine will take into account your style-sheets for header (and footer) and it is easier to manage it (for future modifications).

The way I modified the footer is the same one as used for the header. In general, the footer is simpler and you have less job to do to customize it properly. The initial one which comes with jekyll is reacher than the one I use (it has also a site description and twitter account fields).

Once you created and modified your header and footer files as you want, you have to add some functionalities to the internal links you put in these files. As an example, in the header.html file I posted above, you can see the internal link <a href="/about/"> About</a> which points to the folder /about/. This folder does not exist yet but we have to do something to make this link functional. All we have to do is to create a about.md file and put it in the root folder of the jekyll installation. The content of my about.md file is presented bellow:

---
layout: page
title: About me
permalink: /about/
---
This is the content of "About me" webpage. Easy, isn't?

You see the header part of this about.md file. There are some information to fill in, as layout (the type of content, in this case page), title (the title of your page)and permalink. The field which is very important for your internal links is permalink. In this field you specify the folder which will be created once jekyll engine started and which will contain the index.html file for the current page. And that’s the information you need to use for your internal links.

Another example is the link <a href="/news/"> News </a> which points to /news/ folder. You have to use the same way to create this webpage. You create news.md file, you fill correctly the header fields of the md file (especially permalink which will be /news/ in this case) and that’s it! You created another web page.

##Blog page

All we have to do to finalize our website is to define which page will be used as the blog page. Why we have to do this? Jekyll engine is especially suited for bloggers, but if you won’t to write blog posts, that’s it! Your basic customized web page is given in couple of minutes. But if you want to write some posts on a regular basis, you need one more step to do it properly.

The jekyll initial structure supplies already what you need for this. Fore more information about how to write posts and where you have to put them, see jekyll official website. The file intended to be used as a blog page is index.html in the initial jekyll structure. If you like the way it looks, you can keep it as it is (my case), if not you have to do some works on it to adapt it to your needs.

How to have multiple blogs in a single Jekyll website

You may notice that with the initial jekyll installation, you can have only one web page with posts. You may like to group some posts on different pages according to their categories and you’re wondering how to do it. It’s easy and all you have to do is to copy the content of the initial index.html page into the new page you want to post a specific category of posts and you have also to modify it slightly (as presented here).

That way, in your posts you have to specify the category of your posts and they will be displayed on the page you want. That’s it! I hope that you enjoyed this tutorial!