Jekyll tutorial – all you need to know

In November 2008, Tom Preston-Werner, one of the four founders of the developer platform, GitHub, released the website generator, Jekyll

under the free MIT license. Written in Ruby, it accesses a template directory that contains a set of struc­tures and static text files – markdowns – of different formats. These determine the layout on the one hand, and the content of the web project on the other hand, and can be adapted in­di­vid­u­al­ly for this purpose. The generator does not provide a WYSIWYG editor, but requires classic code writing. Therefore, the content editor, Prose, is rec­om­mend­ed, which sim­pli­fies markdown editing and is optimized for Jekyll.

Before changes to the code are in­cor­po­rat­ed into the live version of the developed web ap­pli­ca­tion, they can be viewed thanks to Jekyll’s own de­vel­op­ment server. The im­ple­ment­ed rendering engine, Liquid, then converts the files into a static website that can be delivered with any standard web server. This au­to­mat­i­cal­ly generates the HTML code in the back­ground when changes are made to the text files.

Here’s how to quickly create a Jekyll website:

But it’s just as easy to create graph­i­cal­ly more advanced websites:

Using Jekyll for blogs and other static web projects is a superior al­ter­na­tive to content man­age­ment systems, con­struc­tion kits, etc. for a variety of reasons. The main advantage of this solution is the sim­plic­i­ty that can be seen in both the work with the website generator and the created projects. Thanks to the pos­si­bil­i­ty of foregoing a database, you save time and effort on the set up and con­fig­u­ra­tion. In addition, the necessary database access is no longer needed, which has a positive effect on the website’s loading time. The min­i­mal­ist code, which is reduced to important functions and features, is present in all Jekyll themes, and con­tributes to good per­for­mance and easy project de­vel­op­ment and main­te­nance. Compared to classic CMS, Jekyll generates a de­liv­er­able markup after each amend and not only when a user accesses a page.

Jekyll also scores well when it comes to stability and security. Since the web server only has to deliver text files, Jekyll’s potential for error is con­sid­er­ably lower than for websites that have several different com­po­nents in­ter­act­ing with each other. And because no regular updates are necessary, the stable code framework also ensures high avail­abil­i­ty of the website in the long term. The security results from the fact that it doesn’t make much sense to attack Jekyll, since it doesn’t have CMS, databases, and scripts with dynamic elements (PHP, JavaScript, etc.).

While the highly-re­strict­ed code base is no obstacle for ex­pe­ri­enced de­vel­op­ers, newcomers will find it difficult to use the website generator. In the standard version, Jekyll does not have a graphical user interface, so in­stal­la­tion and setup must be carried out via the command line. Jekyll is also clearly inferior to many CMS and website de­vel­op­ment tools when it comes to the theme selection, since it lacks choice; other tools have hundreds or even thousands of design and layout templates. The same is true for the support, which isn’t very developed due to its small community and low dis­tri­b­u­tion.

The following table sum­ma­rizes Jekyll’s most important ad­van­tages and dis­ad­van­tages:

First, you need a GitHub account. To do so, go to the GitHub website and enter a valid email address, username, and password for your future account.

Then select the plan you want to subscribe to – the free version for an unlimited number of public di­rec­to­ries or the fee-based one for an unlimited number of private di­rec­to­ries. Lastly, you can op­tion­al­ly provide in­for­ma­tion about your pro­gram­ming skills and interests. You will then receive a con­fir­ma­tion email from GitHub and can then activate your account by clicking on the link in it.

Now that you’ve created an account, you can log into GitHub. The user dashboard gives you an overview of the in­di­vid­ual di­rec­to­ries, but doesn’t provide any in­for­ma­tion at the beginning. To change this and to lay the foun­da­tions for using GitHub Pages, you first have to create a new repos­i­to­ry.

Until now, the directory is a common GitHub project directory. To convert it into your web repos­i­to­ry, you’ve got several options.

• Start from scratch and build your website without a template using Jekyll. For in­for­ma­tion on how to do this, see the official doc­u­men­ta­tion.
• If you use a ready-made Jekyll theme, it’ll be even easier to get started.
• The Jekyll example from Deploy Now is also a great starting place to create your website using the Static Site Generator.

During the theme selection, a con­fig­u­ra­tion file (config.yml) and an index page (index.md) are au­to­mat­i­cal­ly generated. By default, the latter is the preview example for the selected Jekyll theme, which is why it is already available in markdown format. You can edit both the start page and the con­fig­u­ra­tion file by selecting the cor­re­spond­ing file and then clicking on the pen icon on the menu bar.

If the setup has worked as described in the previous steps, you can continue designing your blog or website. All the files you need for this purpose, such as CSS sheets or JavaScript codes, can be created using the 'Create new file' button. This way, you can also create ad­di­tion­al sub-pages for your web project. Via 'Upload files', it is also possible to upload files directly. You can either specify the location or drag and drop the file you want to insert.

Desktop Client

It is possible to manage a Jekyll website com­plete­ly via the GitHub web interface. With the desktop client, which is available for Windows and macOS as already mentioned, there is also an offline solution. If you have not yet installed it, simply click on the button “Set up in Desktop” in the created repos­i­to­ry and you will au­to­mat­i­cal­ly be taken to the download page.

After you have down­loaded and installed the client, you can use it to make a local copy of your website. To do this, simply log in with your GitHub login and select the entry 'Clone a repos­i­to­ry' from the start menu. You now have the option of spec­i­fy­ing which repos­i­to­ry you want to clone. The storage location can be specified under 'Local path'.

You can access different branches in your repos­i­to­ry. These are in­di­vid­ual branches in the project that allow de­vel­op­ers to work on the code si­mul­ta­ne­ous­ly or to focus on specific de­vel­op­ment areas sep­a­rate­ly. IONOS Deploy Now displays the in­di­vid­ual branches of the cloned repos­i­to­ry. As soon as you create a new branch, it is au­to­mat­i­cal­ly displayed using Deploy Now. This way you can always keep an eye on your entire web project and the progress within the in­di­vid­ual de­vel­op­ment branches.