Jekyll Practical Guide

Jekyll on Habrahabr is already glowing. In short: this is a blog-oriented system for generating static sites. The main feature: used on Github Pages, which allows you to keep the source of the site in the repository on Github - and several caching servers within 10 minutes after commits will be collected and displayed to visitors. If more interesting and short: I recommend reading this article , part of which I will mention here. And I will talk about Jekyll in more detail: how it can be used for its intended purpose, why it is not used for its intended purpose, and what he is capable of. The article focuses more on those who have not worked with anything like this before (like me, who previously worked with WordPress), and in most parts of the article Jekyll will be considered exactly as a means of blogging, although closer to the end there will be something completely different.

Of all the existing platforms for blogs (engines, services, generators), Jekyll seemed strange to me. This is rather my fault, because I was carried away by static sites not so long ago and do not know any analogues. Jekyll is aimed at technically literate people who are more interested in using the blog for its intended purpose: publish posts in reverse chronological order, and also provide more or less convenient navigation. If you need more, you will have to either sweat or give up more (well, or from Jekyll). And this way of “communication” is largely determined by the circle of users of this platform: those who need a website with a structure that is extremely clear to them and a minimum of problems in publishing new posts.

Writing posts

The first thing that Jekyll repels most beginners is: the complete lack of a visual (WYSIWYG) editor. This is a conscious failure, not a technical flaw. For the design of their posts, it is proposed to use the Markdown and Textile languages, which are well-readable, even in source codes, markup languages. And with the help of this, the principle of writing posts that is more important for “spherical users of Jekyll in a vacuum” is implemented: WYSIWYM, see what you mean), which is suitable for any text editor, even in the terminal.

The visual editor in Jekyll is missing most likely because it is not very clear where to put it. You will have to save the entered result yourself, the editor will not be able to write it down, the site is static. What imposes two reasonable ways out of the situation:

• Put the editor on some web page, run it in a browser from somewhere and copy the code manually from the browser into the repository
• Use the “prose.io” web application (thanks to Elfet for the tip), hinting at the result (not quite WYSIWYG), but writing the result to the repository yourself
• Leave the work to the editor on the user's computer

I do not know a single user Jekyll, who would use the first method, although I do not exclude that there are such. Yes, you can use the browser-based visual editor, but the whole process of writing a post will be reduced to typing it in the editor and copying the resulting code to a file with a Jekyll post on Markdown (* .md, * .markdown), since no one forbids using Markdown in HTML. Textile did not try, perhaps he will also appreciate this humor. But if you seriously think so to do, think: why do you need Jekyll?
')

Static is not harmful

The second thing that Jekyll pushes away: the static nature of the assembled site, the lack of feedback. This is equally a disadvantage and advantage. Using third-party services, the disadvantages of this feature can be weakened. This approach does not suit everyone, but many. I abandoned WordPress precisely because I used only a very small amount of its functionality, and the rest had to be turned off or even blocked by additional plugins. In the end, I wondered: why should my site get feedback if it is limited to comments posted to the same on a third-party service? Many more blogs just do not need.

By refusing feedback, the hosting requirements can be significantly reduced: for a static site, the server only needs the ability to render pages from the file system, which almost any web server is capable of. Comments provide many services, including Disqus , the search can also be done in several ways:

• Google Custom Search (obviously)
• The form that sends a request to Google with the site: parameter site:
• form the material for the search using Liquid (see below) and force the client to search it
• collect the RSS feed and use the Tapir service (may it spare the habraeffect)

This is enough to start a good blog, which will be convenient to move around when it grows up. And at the same time, from the side of hosting, it is still required only to render pages. Perhaps this is somewhat "wrong" in relation to the client, who will have to make unnecessary requests to other nodes, but how much this disadvantage outweighs all the benefits of static, you decide. Usually does not outweigh.

Hosting Features on Github

Github is primarily a repository of Git repositories. And with reference to sites, this means that it keeps the entire history of changes to your site. Sometimes it is fun to log into the Jekyll site repository and see the entire history of the site by commit. This is not only a fun feature, but also a way to teach other Jekyll users your tricks without any extra effort on your part.

If you think about it, Github is one of the best reasons to use Jekyll. In addition to the advanced web interface of the repository that actually replaces the admin panel (you can create and edit files from it, this is enough for complete control), this hosting will provide the site with a high download speed from wherever Github works well — wherever I am, at a minimum.

There are also a number of features not related to Jekyll itself. Putting 404.html in the root of the repository, you will get your own error page in case the user clicks the broken link to your site. Putting in the root of the text file CNAME with a single line, you attach the domain specified on this line to your site. You will only need to send this domain to Github using DNS.

Why is YAML here

There are enough installation and basic manuals for Jekyll, I’ll talk about something more internal. YAML front matter, which I call the “YAML header”, is a set of structured information about a page or post, written at the very beginning of the file. The closest familiar YAML analog to me, which has serious popularity - JSON. The essence of the language: the representation of some structured data set in text form ( serialization ). And in order to be convenient to structure, it is enough to have two data structures in the language: a list and an associative array (list and map). A simpler language: just a list of values ​​and a list of values ​​with specific names.

YAML here is doing exactly what it should, while maintaining good readability of the data. In most cases, he is interested in simply specifying several values ​​in an associative array: name, date, tags, category. And YAML supports the feeling of WYSIWYM: you understand what the cap means, just by looking at it. But YAML is capable of much more than such primitive instructions.

You can write to YAML absolutely any data: from typical to crazy (bug report has already been sent). The collection of your posts in _posts with caps on YAML is, in fact, the database of your site, and it is not necessary to use it exactly in the form in which it was intended when developing Jekyll. But before you fill the database, you should learn how to use the data from it. About this a little further.

Patterns: the most important thing!

Perhaps the main feature in all static site generators is templates. Because there is no need to copy the same code in several different places, if the computer can do it for you. The whole template system in Jekyll is simple, almost primitive. The template is just an HTML page (in the _layouts folder), which has a Liquid tag (more on them) {{ content }} . And the name of the template is considered to be the file name without an extension: for example, the template foo should be described in the file foo.html .
Any page of the site can link to a template (including another template):

 --- layout: default --- 

When Jekyll collects the page, it is checked whether the layout parameter is specified in the header, as above. If specified, the page is first assembled from the template specified in it, and from the resulting page the {{ content }} tag is replaced with the content of the page being worked on. I will give an example.

I use basically two templates on my website: list and post , but they are not self-sufficient, but are extensions of the default template. In the latter is the outermost shell, used on almost all pages. post displays the post, its tags, and a comment form. list used for various lists of posts, and contains JavaScript, which displays the number of comments for all posts in the list. When building a post in my blog, Jekyll first sees the layout: post in the header, turns to post.html and sees the layout: default . In default.html no templates are specified, so it loads this file, it post.html {{ content }} with post.html (and this is the template, {{ content }} also exists in it) and into the resulting hybrid instead of {{ content }} writes my post.

Theoretically, you can make posts of different types and formats: a full-length article, note, quote, picture. We'll have to strain to post displayed in the lists in different ways, depending on the format, but this is probably the only non-obvious point.

Liquid's unexpected power

To generate a site, you need to describe the rules by which the generation will be carried out. The part is sewn into Jekyll itself, like processing all files in _posts , whose name corresponds to a certain format (date-name), and creating the site structure. It is always and greatly facilitates the work on a blog without frills.

You can also write rules on Liquid or develop Ruby plugins. But with the latter, disappointment awaits you - Github launches Jekyll in “safe mode”, and the generator will not pay attention to custom plugins. If you really need them, you can always generate a website for yourself, and then upload to Github not the source of the site, but the result obtained from the generator. It is reasonable to do this in two different branches of the same repository (as Octopress does). All that you lose with this is the ability to pick up changes in the source immediately after the commit-push without any extra actions. If you work with the site mainly from the same machine, this is not a problem at all: you can write a shell script that will put the site into the folder with your repository, make a date / time commit (for example) and send the changes to Github . But back to what can be done without fear.

Just creating a website on Jekyll, you already get one simple program on Liquid right on the main page. The essence of the program is simple: display all posts available on the site. And the code that does this looks quite readable:

 {% for post in site.posts %} <li><span>{{ post.date | date_to_string }}</span> &raquo; <a href="{{ post.url }}">{{ post.title }}</a></li> {% endfor %} 

Print for each post its publication date and a link to it, indicated by its name. It looks quite logical and short. But this is the easiest format. You probably want to display a small piece of it with each post (“kata” mechanics). The developers of Jekyll have provided for this, and for each post such a piece is recorded in the variable excerpt . In Liquid it can be implemented, for example, like this:

 {% for post in site.posts %} <li> <p><span>{{ post.date | date_to_string }}</span> &raquo; <a href="{{ post.url }}">{{ post.title }}</a></p> <p>{{ post.excerpt }}</p> </li> {% endfor %} 

You can use Liquid to generate a site map (thanks to this person for the thought) and even tag clouds (where the tags used more often are larger, thanks to him ), which is very useful for the site.

YAML + Liquid =?

With embedded variables, everything is more or less clear. But business is not limited to them. Continuing to move on with practical examples, we will look at the page headers used on my website, say, here and here . Each header also comes with an icon from FontAwesome . Inserting an icon from this font (in the old version, like mine) is implemented by the construction:

 <i class="icon-"> </i> 

But you can not write it in the title every time, making the template like this:

 <i class="icon-{{ post.icon }}"> </i> 

... and briefly asking the necessary pages in the YAML header something like this:

 icon: tags 

And this is a relatively simple example. You can store entire data structures in your own variables, and this allows you to do things that may seem insane to some. When I realized that it was possible to do this, I redid the text quest collected in 10 hours with the bare hands of the script, into an automatic assembly using Jekyll. The result can be seen here , including the original version. Each “scene” of a text quest is a “post” in terms of Jekyll, in the YAML header of which there is a “code name”, style of the scene, “illustration” of the scene (icon), a list of links, each of which consists of an icon, text and destination, and some less important trash. Jekyll, on the basis of all the scenes, collects one big page, where the whole quest lies in working condition. An unpleasant side effect is that pages are generated for each scene, but there are no links to them anywhere. How to deal with this, I did not invent.

Conclusion

Once again, I note: Jekyll is not for everyone. But if you read the whole article and it didn’t scare you - perhaps you should try Jekyll in action, you only need the time set by Ruby (preferably) and the basic knowledge of creating web pages. I described the implementation of the functionality that not even all WordPress users use.

Available in Jekyll functionality allows you to do more than just a blog. But this is more of a misuse of Jekyll, although it can be quite an interesting task with a nice bonus of hosting on Github. I didn’t disclose the topic of plug-ins in Ruby for one simple reason: I am absolutely not familiar with this language and the impossibility of using it on Github does not force me to study it. The only two languages ​​that you should learn to use are: YAML and Liquid, and even this is not necessary if you follow the guidelines and do not aim at anything more. However, a meager and primitive blog is not needed for very few people, unless something completely unique and extremely useful is posted there.

In general, try if you feel the strength and determination. And if you have not tried anything like this before.