Jekyll

In a post on site re­launch I told I’ll write a lot of ar­ti­cles on Jekyll. That’s the first post in the se­ries, an in­tro­duction.

I won’t write on how to in­stall Jekyll, how the files are struc­tured there, and so on —there are al­ready a lot of ar­ti­cles on that (look for some at the links). To de­scribe Jekyll briefly, it’s a blog-aware sta­tic site gen­er­a­tor. An awe­some one.

GitHub Pages

I need to tell one thing from the start: this and all other fu­ture ar­ti­cles would be in the con­text of GitHub Pages. While GitHub al­lows you to host any sta­tic sites on it, there is also a way to host sites wrote with Jekyll. So, the Jekyll is the only way to ac­tu­ally gen­er­ate some­thing right at GitHub with­out use of any other ser­vices or any front-end so­lu­tions.

With Jekyll you can just cre­ate a file in mark­down, add a YAML front mat­ter to it —and start writ­ing. Af­ter push­ing this file to the repo on GitHub, the whole site would be re­gen­er­ated and you’ll see the cor­re­spond­ing post both as a page on your site and in all the list­ings 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 us­ing GitHub’s API.

And an­other thing I need to men­tion right from the start: a lot of things I’ll de­scribe in the next ar­ti­cles could be made so mush eas­ier us­ing plu­g­ins. But I won’t go an easy way —I’d like to make every­thing in a way more peo­ple could use it: even in places where the plu­g­ins are dis­abled —as on GitHub Pages.

Hello world”

Min­i­mal doc­u­ment you’ll need to gen­er­ate a site on Jekyll should con­tain the YAML front mat­ter with at least one field —lay­out (you could ac­tu­ally make one with­out it, with empty YAML front mat­ter, but in that case your page won’t have any lay­out at all). So, the min­i­mal hello-world.md for Jekyll would look like

---
layout: default
---

Hello world!

In real world you’d like to add at least a ti­tle or some other data, but for the most triv­ial cases that’s the min­i­mal code to start from.

Dates

One of the fea­tures I like in Jekyll is its for­mat for posts. You need to name the files as YYYY-MM-DD-ti­tle and I think that’s awe­some. It makes you to main­tain a bet­ter file hi­er­ar­chy that would be sorted by date au­to­mat­i­cally, and also you won’t need to write the date in the post it­self —Jekyll would use the date from the file­name. Yes, in some cases you’ll want to use the pub­lished field in YAML to over­ride the date from the file­name, but it’s up to you. In most cases you won’t need it.

Prose.io

And if you don’t like to fill up YAML by your­self, and you don’t want to use any scripts for it (like it’s done in Jekyll Boot­strap), you could use a ser­vice like Prose.io. This awe­some ser­vice al­lows you to de­scribe all the meta­data de­faults in a con­fig, so when you cre­ate a new post us­ing Prose, all the meta­data would be filled for you (ac­tu­ally, in most ba­sic cases you’d need to at least look at the meta­data, but that’s an­other story I’ll tell some­day later).

There is a lot of use­ful info in the in­ter­nets on Jekyll, I’ll try to sum all the use­ful links in this post for you (and for my­self). There are links that would help you to start with Jekyll, and the links that are use­ful all the time you’re tin­ker­ing with the logic be­hind Jekyl­l’s tem­plates.

There are also a lot of help­ful pages on Jekyll in the Jekyll Boot­strap pro­ject. I found those ones to be the most useful:

Jekyll uses Liq­uid for tem­plat­ing. GitHub re­cently up­dated Jekyll, so now you could use al­most all the tags from the docs:

Be­fore this up­date you could­n’t use the pow­er­ful split tag —al­most the only way to make a lot of dif­fer­ent things with Jekyll (guess what —there would be some ar­ti­cle on me hack­ing with that tag).

For writ­ing posts I rec­om­mend to use mark­down. While there are other ways, like plain HTML or Tex­tile, for most cases the mark­down would fit the best.

  • For a mark­down en­gine I’d rec­om­mend to use kram­down —it’s the best op­tion so far, I’d write why in one of the next ar­ti­cles.
  • For con­fig­ur­ing the site or any spe­cific post you’ll need to use YAML —so if you’re not fa­mil­iar with its syn­tax —go and read about it, it’s nice.

Over­all, I’m very happy I’ve cho­sen the Jekyll for my new site. There are a lot of is­sues with Liq­uid tem­plates, but the over­all re­sult has been worth it.