Jekyll 2 is coming on Github!

    Post-publish: Some reservations about the "old version" should be taken seriously - Jekyll 2.2.0 is already installed on Github. The topic was written when version 1.5.1 was relevant on the github.

    Jekyll Logo
    An interesting situation has developed. Jekyll is now on version 2.1.1, and Github collects sites with the obsolete (but reliable) version 1.5.1 (at the moment, the current information is here ). On this, some have already stumbled upon receiving assembly errors when, according to the documentation from the Jekyll website, everything is in order. Avoiding such incidents is easy - you need to use notjekyll, butgithub-pagesso that the versions coincide with those deployed on the github. Fresh versions, at the cost of some complications in the publication process, can also be used. The method is widely known and will be described later, but first you need to understand, "why all this?"

    The transition to 2.x is slowly going on . Innovations are cool and many are looking forward to them. Is it worth it? Let's think ... but first, let us introduce those who first encountered Jekyll.

    Jekyll? What is it? I need it?

    This is a well-known generator of static blog sites. You have a set of files in the convenient Markdown and Textile markup languages , as well as templates in HTML / CSS / JS, you launch Jekyll and get a set of regular HTML pages that you can download almost anywhere, under the guise of a site. Do you need it? Good question.

    For sites that rarely change, static pages are a good choice, they are undemanding to server resources: if only they would render 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 computing power of the server will not significantly affect the speed of the site - the network bandwidth will play a big role.

    Strictly speaking, even some so-called "Dynamic" sites with caching enabled behave in much the same way. Gathered a page - save for others, so as not to collect a new one every time. But it all comes down to how often the site changes. For most business card sites and portfolios, a static site is a good form factor, as they rarely change.

    Jekyll - because github

    Static sites are interesting in that they are a collection of HTML pages. If you upload gh-pagessuch a set to Github , it will perceive them as a site, and will send it to some address (which one is better written in the documentation about this ). Therefore, it is not necessary to use Jekyll for publication. Any static page generator will work.

    But Jekyll is special. Github can collect site pages using Jekyll automatically, immediately after changing the sources in the corresponding repository. Whether it’s your personal website, the organization’s website on a github or a project, you can safely use it. This is precisely the reason why he is so well known. Additional information can be found on the github itself , you can also readmy previous post (there are many links) .

    Formally, Jekyll can be extended with plugins. But since Jekyll collects sites in a safe mode on a github, no plugins will be accepted during assembly, which, if any, forces the site to be assembled locally, and the source files should be stored separately from the site itself. Therefore, many are waiting for the new functionality to be added to Jekyll itself, so as not to do so. Personally, I sometimes need to make a small edit to the site, and it is extremely convenient to do this with the editor from the web interface of the github. And there are many like me.

    To the point, finally!

    I did not manage to find where backward compatibility is broken. Basically, Jekyll 2 provides extensions to what is already there. In any case, so far the matter is not about plugins that Github still does not process.

    Now you can outweigh the gigabyte by the tangible amount of work that some users previously performed on their own machine. But let's start with a less important thing, more interesting for new users.

    New default template

    A cosmetic change is largely 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 show any new features of Jekyll! Therefore, I started with him.

    For beginners, this, however, is rather good news, because the new template is visually nicer than the old one and 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 here's how the new one looks:

    Screenshot of the new template

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

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

    This is where the information for beginners ends. More significant features follow, 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 terms.

    Sass and CoffeeScript

    Have you heard about Sass ? If not, and you don’t want to read the official site, I’ll tell you briefly: this is “finished CSS”. The closest analogue is Less , and it is rarely possible to meet a person who knows only about one of the two, more often both or none. The most significant improvements over CSS: variables, functions, impurities (mixins, thanks to the term Mithgol and difiso for the term ) 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 take out repeated or generated pieces in special places, but these are not all features. The output is a regular static CSS file that browsers can understand.

    What does this mean for Jekyll? Now you can store style sources in the repository with the site. Especially if your site uses a framework written in Sass for appearance. You can take the sensational Bootstrap , which is written in LESS , but also has a port in Sass . In what order and what to embed in Jekyll, I will explain a bit below.

    There is a bun for those who work with CoffeeScript : now it is not necessary to collect JavaScript files each time before publishing, you can store the source directly in the repository. But personally, I do not use it and cannot tell about it in more detail; In addition, 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 any place of the project will be processed if it contains “YAML front-matter” - a header from metadata in the YAML language. It’s just a block at the beginning of a file between two lines with the contents of “---”, in which you can define individual values, lists and objects (also known in different circles as maps and hashes) relating to this particular file and / or those who this file inherits. We already saw this approach in Jekyll posts, this also affects resources, only in the case of resources the header is often empty. In any case, the documentation advises you to do this : we write three hyphens in the first two lines of the file, Jekyll sees an empty header in them and processes the file.

    At the moment, the three recognized file extensions: .sass, When building a site, a file .css(from Sass) or .js(from CoffeeScript) is written to the appropriate place .

    Sass is beautiful

    ... and I'll tell you why.

    It has the ability to export individual code fragments to files (partials), and subsequently import them ( @import "файл";). Import comes from some “project folder”. It can be customized. By default it is _sass. That is, if you import something into Sass (and did not change the configuration file for this purpose), create a folder in the root of the site _sassand put all the imported content there. One of the features that suddenly arises from this is for fans to squeeze everything out for performance: you can glue all CSS into one file and thus reduce the number of HTTP requests, but also the volume (the Sass preprocessor has an option to compress the result). What can I put there, besides what you wrote?

    For example, you can put the contents therehere this daddy , and then make one of your sass / scss files @import "bootstrap"and get a full Bootstrap with the ability to change its sources and collect them automatically when changed. A large part 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: changing the result is time-consuming, since there are quite a lot of dependencies in the styles in different parts. In the end: it either looks too complicated, or requires a ton of various trash to be delivered . In fact, everything is completely wrong, but it looks that way .

    You can import there any of the libraries written in Sass, like Compass orBourbon . However, libraries (sass / scss files), with high probability, will have to be copied directly to _sass, since it is not known whether they will be available on the github, there is no information about this. Probably not. If Git allowed submodules to specify not entire repositories, but separate folders in them, everything could be much simpler. But in this regard, changes are not worth waiting in the near future. I remind you that before building the site, Github loads all the submodules specified in the repository, which is useful for taking out files used in several places at once, like the library assembly you need.

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


    It has never been impossible to get its convenient API. Which, however, is not yet considered complete, and may change :
    Collections support is unstable and may change
    This is an experimental feature and that the API may likely change until the feature stabilizes.
    This was needed mainly for those who really wanted to use Jekyll not for a blog (I won’t point a finger at anyone). In Jekyll 1.5.1, pages are divided into the following collections: site.posts(all blog posts), site.pages(all pages, no 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.projectsfor projects in which you participated. Strictly speaking, a similar thing could have been done before using tags on posts, but this looks more like a hack than a feature.

    Data files

    In essence, this is the ability to define data that is global for the entire site. Also an innovation from the category of "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 object site. The only question was whether you were ready to inflate it.

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

    For what? With this, it’s much easier to prepare code for reuse by someone else. For installation, you do not need to replace existing files, while the configurable parameters will be taken out to a special separate place. Perhaps there are other ways to take advantage of this: let's say you can describe the structure of the menu 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, the presence of which indicates the “development environment”. It may exist on the developer's machine, but be absent in the version control system (it .gitignorewill help), and thus not get into production. Accordingly, if this file (suppose development.json) exists, then the object also, which means that you can print some kind of debugging data without performing any additional actions during deployment. A trifle, but nice.


    You can read about the rest on Jekyll's blog , because I have nothing to add to the rest. This does not mean that there are no major changes - even as it is.

    For example, using the Liquid filtergroup_by , you can beat certain objects (posts or something else) into groups according to an arbitrary attribute. Using this, you can, for example, create a complex catalog of something with several ways of splitting. Not very similar to the task for which Jekyll is suitable, but it's more about technical feasibility, rather than expediency:

    Why make a trolley bus from a loaf of bread?

    In sum, the innovations somewhat divert Jekyll from the niche of blogs, allowing you to collect more complex things on it. Due to the abundance of possibilities for transferring parameters to configuration files (different!), It has become easier to share your own code with other Jekyll users, while maintaining the ability to easily configure it without having to describe what and where it is regulated, and also without the need to replace files that already exist. Everything can be described directly in the YAML file, in the comments (a single-line comment follows after #). But it should be remembered that the output is the same static pages, so far from everything can be implemented on the basis of Jekyll.

    I would like to believe that this will lower the threshold for joining Jekyll for those who previously considered it too difficult; but it depends more on whether the Jekyll community takes advantage of the innovations to help newcomers settle down in this unusual world of static sites.

    For my part, I am going to complete the Sass snippet for highlighting the Pygments syntax (and compatible ones) so that the highlight can be entered in any color scheme. But I'm alone, the community is large, and Jekyll 2 is still not installed on the servers of the github, 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 the “reasonable”, but from the point of view of the “possible”. Do not take this as an excuse to try Jekyll in your next project, as the purpose of this tool can be very different from your goals. If to complete your task with Jekyll you have to use everything that is in it, and add a lot of hands with the help of the template engine - you may have made a mistake with the tool. Are you ready to apply all this just to ensure that your site is automatically collected from the source by Github servers? You decide.

    Also popular now: