What is Jekyll?
Jekyll is a static site generator that takes simple raw text files and spits out
a static web site suitable to be published on your favorite webserver.
The key here is simple raw text. Yes, because the convenience, funny and nerd
thing(from a developer point of view) is that you can write those files in your
preferred way: HTML, Markdown or Textile.
Then you can make your own blog, you can convert your old blog etc...It is really really powerful.
Let's start
While Jekyll is fully supported in linux environment, it is not for windows environment, or at least not officially. For installation on windows follow special instructions --> Here.
In a linux machine you have to satisfy a couple of requirements. You have to
install:
Ruby
RubyGems
Once you have installed requirements, you can install Jekyll executing the command:
# gem install jekyll
That's it.
Second step..
Let's build our website in our home folder in five commands:
$ cd $HOME #to be sure to be in our home folder
$ jekyll new Blog #Jekyll creates our blog
$ cd Blog </code>
$ jekyll build #Jekyll converts the raw text in html
$ jekyll serve #Jekyll runs a local webserver to test our website
Now click --> Here
You have your static web site.
Let's have a closer look..
If you check the folder tree of Blog you will see something like this:
├── _config.yml
├── _includes
| ├── footer.html
| └── header.html
├── _layouts
| ├── default.html
| └── post.html
├── _posts
| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
| └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
└── index.html
First thing to notice and to remember is: files and folders with an underscore as prefix will not be published. Everything you want to show on your website should not have that prefix.
_config.yml
As its name says it is the configuration file for Jekyll. Here we can define and
customize settings as we prefer. Some are self explanatory some other are not.
For example:
source: .
destination: ./_site
plugins: ./_plugins
layouts: ./_layouts
Here we are saying to Jekyll that he will find our source files into the current folder(.), that he should put our website into _site folder, and he will find templates inside _layout folder.
Full explanation of every setting --> Here
Templates
Jekyll works by means of layouts (or templates). HTML and CSS teaches us to split
layout from contents. Jekyll forces you to do exactly this.
Inside every layout we will define the layout indeed, but also we will inject the content with
a special markup language called Liquid --> Here.
Always referring to our Blog, into _layouts/default.html you have to write everything that form the layout
of your website (to be as clear as possible: everything that will be visible in every page of your website).
For example: the header, the footer, the navigation bar etc..
This will be our base layout.
Then you can create any other sort of layout in two ways:
1. From scratch (if you have to create a completely new layout)
2. Simply specializing default layout. We will see how, very shortly
Every layout you create goes into _layouts folder.
Liquid template
Very briefly, liquid template is a markup language that gives you the possibility to create a
template without jeopardize the security of the webserver.
It is used to inject the content of the page/post into the layout by means of variables and their contents.
If you have a look to Blog/_layout/post.html
you can see something like {{ content }}
.
content is called Output tag and will be converted by Jekyll to the value associated with the tag.
There are also Logic Tags to define loops, conditional, assignments etc.. It is a little and simple
programming language.
To see which variables Jekyll defines --> Here
YAML Header
To make the Jekill's magic possible, we have to tell Jekyll to treat pages and posts in a special way. We can do this writing something an header like this:
---
layout: default
title: Title of my page
---
We are telling to Jekyll : convert this page using the default layout and keep Title of my page inside the variable title. Then taking advantage of liquid template we can write something like:
<!DOCTYPE HTML>
<html>
<head>
<title>{{ page.title }}</title>
</head>
<body>
...
IMPORTANT: inside the header you cannot type any tab spacing(pay also attention if you are using some IDE with automatic code formatter). The exact format must be the one I showed above. You can define your own variables inside any YAML header and use it in the same way I did.
An example could be:
---
layout: default
title: My page with Jekyll
myvar: Jekyll is awesome
---
<!DOCTYPE HTML>
<html>
<head>
<title> {{ page.title }}</title>
</head>
<body>
<p>
I have to say that {{ page.myvar }}!
</p>
...
Permalinks
Jekyll gives you the possibility to choose the format of your permalinks, globally or page by page. The default one is called date. Jekyll will generate a permalink like this:
/:categories/:year/:month/:day/:title.html
Other options are (Copy & paste from official documentation --> Here):
Permalink Setting | Resulting Permalink URL |
---|---|
None specified, or |
|
|
|
|
|
|
|
|
|
Inherit default layout
We can write different layouts simply specializing the default one.
How? Using the YAML header.
Inside _layout
folder we create another file, let's say, mylayout.html
with this header:
---
layout: default
---
Then you can write everything you want to create your own layout.
For example I wantet to create a post (this one you are reading). So I created a file post.html
and I wrote this:
---
layout: default
category: blog
title : How I Developed this Website
---
<div class="header">
<h1>{{ page.title }}</h1>
<p>{{ page.date }}</p>
</div>
<div class="content">
{{content}}
</div>
That is it! You can see the result with your own eyes.
Writing Post
Once you defined a post layout you can start writing posts.
A very important thing to begin with is the name of the file and where to put the file.
The name must be EXACTLY like this year-month-day-title.extension
You can write it in YAML, Markdown, HTML, so extension should be yml
or yaml
, md
, html
.
The file must be put inside post folder.
Writing Page
You can write a page following two different way.
1-You create a folder and inside you will create a file called index.html, for every page you create.
2-You create different files with different names for every page.( ex. about.html, my_page.html etc..)
Integration with Git
Jekyll is fully compatible with Git.
You can create your own repository and keep development of your site versioned with Git.
Github offers a completely free hosting for sites, like mine.
Other things you should know..
There are also other useful folder in Jekyll.
For example the _include
folder. Here you can put every kind of file you want and with the command
{% include file.html %}
you can include the content of that file
where you prefer. For example to include your own source code in a specific point of a page.
_data
folder. Using YAML markup language, we can store relevant(to us or our website) custom data.
We have to create a file inside _data
folder: for example members.yml
.
Then we write for example a list of data:
- name: Tom Preston-Werner
github: mojombo
- name: Parker Moore
github: parkr
- name: Liu Fengyun
github: liufengyuns
Then we can access to this data with the variable: site.data.members
<ul>
{% for member in site.data.members %}
<li>
<a href="https://github.com/{{ member.github }}">
{{ member.name }}
</a>
</li>
{% endfor %}
</ul>
Troubleshooting
Data folder
This feature is available from Jekyll version 1.3 and up.
Invalid byte sequence in US-ASCII
It can happens that building your blog this error comes out. The solution is to set your locale setting to utf8
.
How to do it, depends from your SO. I use gentoo so I did:
# touch /etc/env.d/02locale
# echo /etc/env.d/02locale > LANG="en_GB.utf8"
# env-update
# source /etc/profile
Suggestions
A good starting point could be editing the blog Jekyll created for us.
You can follow the official documentation about Jekyll to know details not covered here.
Customize your _config.yml
file to satisfy your needs.