In a post on site relaunch I told I’ll write a lot of articles on Jekyll. That’s the first post in the series, an introduction.

I¬†won‚Äôt write on¬†how to¬†install Jekyll, how the files are structured there, and so¬†on¬†‚ÄĒ there are already a¬†lot of¬†articles on¬†that (look for some at¬†the ‚Äúlinks‚ÄĚ). To¬†describe Jekyll briefly, it‚Äôs a¬†blog-aware static site generator. An¬†awesome one.

itHub Pages

I need to tell one thing from the start: this and all other future articles would be in the context of GitHub Pages. While GitHub allows you to host any static sites on it, there is also a way to host sites wrote with Jekyll. So, the Jekyll is the only way to actually generate something right at GitHub without use of any other services or any front-end solutions.

With Jekyll you can just create a¬†file in¬†markdown, add a¬†YAML front matter to¬†it¬†‚ÄĒ and start writing. After pushing this file to¬†the repo on¬†GitHub, the whole site would be¬†regenerated and you‚Äôll see the corresponding post both as¬†a¬†page on¬†your site and in¬†all the listings on¬†other pages as¬†well. And you could push your changes from any place: you could even use just GitHub‚Äôs site for this or¬†any web app using GitHub‚Äôs API.

And another thing¬†I need to¬†mention right from the start: a¬†lot of¬†things I‚Äôll describe in¬†the next articles could be¬†made so mush easier using plugins. But I¬†won‚Äôt go¬†an¬†easy way¬†‚ÄĒ I‚Äôd like to¬†make everything in¬†a¬†way more people could use¬†it: even in¬†places where the plugins are disabled¬†‚ÄĒ as¬†on¬†GitHub Pages.

‚ÄúHello world‚ÄĚ

Minimal document you‚Äôll need to¬†generate a¬†site on¬†Jekyll should contain the YAML front matter with at¬†least one field¬†‚ÄĒ layout (you could actually make one without¬†it, with empty YAML front matter, but in¬†that case your page won‚Äôt have any layout at¬†all). So, the minimal hello-world.md for Jekyll would look like

layout: default

Hello world!

In real world you’d like to add at least a title or some other data, but for the most trivial cases that’s the minimal code to start from.


One of¬†the features¬†I like in¬†Jekyll is¬†its format for posts. You need to¬†name the files as YYYY-MM-DD-title and¬†I think that‚Äôs awesome. It¬†makes you to¬†maintain a¬†better file hierarchy that would be¬†sorted by¬†date automatically, and also you won‚Äôt need to¬†write the date in¬†the post itself¬†‚ÄĒ Jekyll would use the date from the filename. Yes, in¬†some cases you‚Äôll want to¬†use the published field in¬†YAML to¬†override the date from the filename, but it‚Äôs up¬†to¬†you. In¬†most cases you won‚Äôt need¬†it.


And if you don’t like to fill up YAML by yourself, and you don’t want to use any scripts for it (like it’s done in Jekyll Bootstrap), you could use a service like Prose.io. This awesome service allows you to describe all the metadata defaults in a config, so when you create a new post using Prose, all the metadata would be filled for you (actually, in most basic cases you’d need to at least look at the metadata, but that’s another story I’ll tell someday later).

There is a lot of useful info in the internets on Jekyll, I’ll try to sum all the useful links in this post for you (and for myself). There are links that would help you to start with Jekyll, and the links that are useful all the time you’re tinkering with the logic behind Jekyll’s templates.

There are also a lot of helpful pages on Jekyll in the Jekyll Bootstrap project. I found those ones to be the most useful:

Jekyll uses Liquid for templating. GitHub recently updated Jekyll, so now you could use almost all the tags from the docs:

Before this update you couldn‚Äôt use the powerful split tag¬†‚ÄĒ almost the only way to¬†make a¬†lot of¬†different things with Jekyll (guess what¬†‚ÄĒ there would be¬†some article on¬†me¬†hacking with that tag).

For writing posts I recommend to use markdown. While there are other ways, like plain HTML or Textile, for most cases the markdown would fit the best.

Overall, I’m very happy I’ve chosen the Jekyll for my new site. There are a lot of issues with Liquid templates, but the overall result has been worth it.