Jekyll 2 is coming on Github!

Post-publish: Some reservations regarding the “old version” need to be taken seriously - Jekyll 2.2.0 is already installed on Github. The topic was written when version 1.5.1 was relevant for github.


There was an interesting situation. Jekyll is now on version 2.1.1, and Github is collecting sites with an outdated (but reliable) version 1.5.1 (for the moment, the latest information is here ). On this, some have already stumbled, having received assembly errors, when according to the documentation from the Jekyll website everything is in order. Avoiding such incidents is easy - you need to use not jekyll , but github-pages , so that the versions coincide with those deployed on the githaba. Fresh versions, at the cost of some complications in the publishing process, can also be used. The method is widely known and will be described further, but first you need to figure out "why all this?"

The transition to 2.x goes on the sly . Innovations are great and many are eagerly awaiting them. Is it worth it? Let's think about it ... but first we’ll get into the picture the cases of those who first encountered Jekyll.
')

Jekyll? What is it? I need it?

This is a famous generator of static blog sites. You have a set of files in convenient Markdown and Textile markup languages, as well as templates in HTML / CSS / JS, you run Jekyll and get a set of regular HTML pages that you can download almost as a website. Do you need it? Good question.

For sites that rarely change, static pages are a good choice, they are undemanding of server resources: if only he would give the files correctly. Some servers (nginx?) Cope with this task so well that they are used as a proxy server for static resources of more complex applications. But when the entire site is static, such a server can be used as the main one, and the server’s processing power will not significantly affect the speed of the site — the network’s capacity will play a big role.

Strictly speaking, even some so-called. “Dynamic” sites behave much the same when caching is enabled. Collected a page - we will save for others not to collect on new each time. But everything depends on how often the site changes. For most business cards and portfolio sites, a static site is a good form factor since they rarely change.

Jekyll - because Github

Static sites are interesting because they are a set of HTML-pages. If you upload such a set to the gh-pages branch on Github, it will take them as a site and give it to some address (which is better written in the documentation ). Therefore, it is not necessary to use Jekyll for publication. Any static page generator will work.

But Jekyll is special. Github can build site pages with Jekyll automatically, immediately after changing the source in the corresponding repository. Whether it is your personal site, the site of an organization on a githaba or a project, you can safely use it. This is the reason why he is so well known. Additional information can be found on the github itself , you can also read my previous post (there are many links) .

Formally, Jekyll can be expanded with plugins. But since Jekyll on the githaba collects sites in safe mode, no plugins will be accepted during the build process, which, if available, forces the site to be built locally, and the source code should be kept separate from the site itself. Therefore, many are waiting for new features to be added to Jekyll itself, so as not to do so. Personally, I sometimes have the need to make a small edit to the site, and it is extremely convenient to do it as an editor from the github web interface. And there are a lot of people like me.

To the point, finally!

I could not find where backward compatibility is broken. Basically, Jekyll 2 provides extensions to what is already there. In any case, as long as the case does not apply to plug-ins, which Github still does not handle.

On the githab it is now possible to outweigh the sizeable amount of work that some users used to do on their own machine. But let's start with a less important thing, interesting rather to new users.

New default template

A cosmetic change, in many respects useless - many still end up writing their own template, and nothing remains of the original (almost?). But what is more sad - the new template does not demonstrate any new features Jekyll! That's why I started it from him.

For newbies, this is, however, rather good news, because the new template is visually more pleasant than the old one and is written in understandable HTML5 (using new purely semantic tags). You can look at the old style on the site of one of the Jekyll developers (and part-time co-founder of GitHub) , but what the new one looks like:



Using the new template is simple: install Ruby and RubyGems (the method depends on the OS), install Jekyll:
gem install jekyll
... or update if you already have one:
gem update jekyll
... and then create a new website:
jekyll new hello_world
... in the hello_world folder (or another if you specified another):
cd hello_world
... and run!
jekyll serve
If everything went smoothly, on this link (http: // localhost: 4000 /) you will see the site template.

However, remember that this is the latest version of Jekyll , and it is not yet on Github . Assembling the “mirror” of the Github environment is also easy:
We load the periodically updated list of libraries in this environment:
gem install github-pages
Write to the Gemfile a list of these libraries:
github-pages versions > Gemfile
Install their bundler (most likely, you already have one):
bundle install
Is done. You can type jekyll --version in order to make sure that it shows version 1.5.1 (relevant at the time of this writing).

On this information for beginners ends. Further more significant features go, and in the descriptions I will assume that the reader has an understanding of how Jekyll works. Nevertheless, I will try to explain in simple language.

Sass and CoffeeScript

Have you heard about Sass ? If not, and you do not want to read the official website, I will tell you briefly: this is “completed CSS”. The closest analogue is Less , and you rarely find a person who knows only about one of the two, most often both or none. The most significant improvements over CSS are: variables, functions, impurities (mixins, for the term thanks to Mithgol and difiso ) and the inheritance of several varieties. These features greatly simplify the writing of complex styles with a large number of dependencies inside, allowing you to make repeated or generated pieces in special places, but these are not all the features. The output is a regular static CSS file that browsers understand.

What does this mean for Jekyll? Now you can store in the repository with the site also source codes of styles. Especially if your site uses the Sass framework for appearance. You can take the sensational Bootstrap , which is written in LESS , but has a port on Sass . In what order and what to insert in Jekyll, I will explain a little lower.

There is a bun for those who work with CoffeeScript : now it’s not necessary to collect JavaScript files before publication, you can store the source directly in the repository. But personally, I do not use it and can not tell you more about it; besides, I doubt the usefulness of CoffeeScript for such sites (but this is my subjective opinion, and I'm probably wrong).

Recall how Jekyll works. Any file in an arbitrary place of the project will be processed if it contains “YAML front-matter” - a header from the metadata in the YAML language. It is just a block at the beginning of the file between two lines with the contents of "---", in which you can define individual values, lists and objects (also known as mapy and hashes in different circles), regarding this particular file and / or those This file inherits. We have already seen this approach in Jekyll posts; this also affects resources, only in the case of resources, the header is often empty. In any case, it advises to do the documentation : we write three hyphens in the first two lines of the file, Jekyll sees in them an empty header and processes the file.

Currently, three file extensions are recognized: .sass , .scss and .coffee . When assembling a site, the .css file (from Sass) or .js (from CoffeeScript) is written to the appropriate place.

Sass is beautiful

... and I'll tell you why.

It is possible to make separate code fragments into files (partials), and subsequently import them ( @import ""; ). The import comes from a certain “project folder”. It can be customized. The default is _sass . That is, if you import something into Sass (and did not change the configuration file for this purpose), create the _sass daddy in the site root and put all the imported content there. One of the features that suddenly emerges from this is for those who like to squeeze everything out for performance: you can glue all the CSS into one file and thus reduce the number of HTTP requests, or you can reduce the volume (the Sass preprocessor has an option for compressing the result). What can you put there, except what is written by you?

For example, you can put the contents of this daddy there , then make @import "bootstrap" in one of your sass / scss-files and get a full-fledged Bootstrap with the ability to change its sources and build them automatically when changed. Much of the web now looks monotonous due to the use of default styles. Often this happens for the reason that people do not reach the self-assembly of CSS frameworks: it’s time consuming to change the result, because there are quite a lot of dependencies within different parts within the styles. The bottom line: it either looks too complicated, or requires you to deliver a ton of various trash . In fact, this is not the case at all, but it looks that way .

You can import any of the libraries written in Sass, like Compass or Bourbon . However, libraries (sass / scss files) will most likely have to be copied directly into _sass , since it is unknown now whether they will be available on the githaba, there is no information about this. Most likely no. If Git would allow submodules to specify not entire repositories, but separate folders in them, everything could be much simpler. But in this regard, changes are not expected in the near future. I remind you that before assembling the site, Github loads all the submodules specified in the repository, which is useful for bringing out files used in several places at once, such as the libraries you need.

BONUS: syntax highlighting using Pygments or Rouge (another new feature of Jekyll 2.0) requires its own CSS styles. They can be generated directly in Pygments, which I have already done (and no longer want), but you can take this juicy Sass piece and substitute your own colors in two accounts (thanks to the post and its author for the original Pygments adaptation to Sass). You can start with the base16 color schemes , but I went ahead and tried to write a generator of such schemes from the same sample color. Sass is a very powerful tool, comparable in power with Liquid, but intended for other purposes, they are not bad combined.

Collections

Never being impossible got its handy API. Which, however, is not yet considered complete, and may change :

Collections support is unstable and may change
This is an experimental feature.

It was necessary mainly for those who really wanted to use Jekyll not for the blog (I won’t point the finger at whom). In Jekyll 1.5.1, pages are divided into the following collections: site.posts (all posts from the blog), site.pages (all pages, without posts) and site.tags (posts under each tag).

With the help of collections you can now create your own set of pages, which will not be included in any of the previously defined. For example, site.projects for projects in which you participated. Strictly speaking, the same could have been done before with the help of tags on posts, but this is more like a hack than a feature.

Data files

In essence, this is the ability to define data that is global to the entire site. It was also an innovation from the category “it was, but it became more convenient.” It was always possible to define global data in _config.yml , and they would appear directly in the site object. The only question was whether you are ready to inflate it.

Now everything is a little easier. It is enough to create the _data folder in the root of the site, and place the data files in JSON or YAML in it, and they will be available in the Liquid template tags in the eponymous (with the file without extension) object inside site.data . That is, the data from the mydata.json file will be available in the site.data.mydata object. Pretty cumbersome, but for things that need a shortcut, there is _config.yml .

For what? With this, it is much easier to prepare code for reuse by someone else. For installation, you will not need to replace existing files, with the custom settings will be moved to a special separate place. Perhaps there are other ways to benefit from it: for example, you can describe the menu structure with their help, if you have a website with a complex structure.

With this you can come up with some interesting tricks. One of them is a file whose presence indicates a “development environment”. It may exist on the developer's machine, but be absent from the version control system ( .gitignore will help), and thus not get into production. Accordingly, if this file (say, development.json ) exists, then the site.data.development object also site.data.development , which means that you can print some debugging data without performing any additional actions during deployment. Trifle, but nice.

Finally

The rest can be read on the blog Jekyll , because the rest I have nothing to add. This does not mean that there are no more serious changes - as it is.

For example, with the help of the Liquid-filter group_by , you can beat certain objects (posts or something else) into groups on an arbitrary basis. Using this, you can, for example, create a complex directory of something with several partitioning methods. Not very similar to the task for which Jekyll is suitable, but it’s rather a technical possibility, rather than expediency:



In the sum of innovations, Jekyll is somewhat diverted from the blog niche, allowing to collect more complex things on it. Due to the abundance of options for the removal of parameters in the configuration files (different!), It became easier to share your own code with other Jekyll users, keeping it easy to configure without needing to describe what is regulated and where you need to replace files that already exist. Everything can be described directly in the YAML file, in the comments (followed by a single-line comment). But it should be remembered that the output is all the same static pages, so not everything can be implemented on the basis of Jekyll.

I want to believe that this will lower the threshold of entry into Jekyll for those who previously considered it too difficult; but it depends more on whether the Jekyll community will take advantage of the innovations to help newbies get settled in this unusual world of static sites.

For my part, I am going to finish the Sass snippet for highlighting Pygments (and compatible) syntax, so that the highlighting can be entered in an arbitrary color scheme. But I am one, the community is large, and Jekyll 2 is still not installed on the github servers, so many Jekyll users have not yet used the innovations and are not even preparing for their appearance.

Of course, I describe Jekyll not from the point of view of “reasonable”, but from the point of view of “possible”. Do not take this as a reason to try Jekyll in the next project, because the purpose of this tool may be very different from your goals. If to perform your task with Jekyll you have to use everything that is in it, and add a lot of things with your hands using a template engine, you may have made a mistake with the tool. Are you ready to apply all this just for the sake of your site being automatically built from source by Github servers? You decide.