Setting Up Jekyll Environment

Last modified 01 Mar 2024 09:18 +01:00

Work in progress

Following information may be useful if you plan to make any development of the Jekyll-based sites, such as adjusting stylesheets, plugins or javascript code.

It is usually not a good idea to do development directly on productions sites. Mistakes will happen, the sites will break, people will complain. Therefore, it is better to use other options for development:

Prototype site. The https://proto.priv.evolveum.com/ site is dedicated for development and testing. Deprecated, currently not available.
Your own Jekyll. You can setup Jekyll and all the other bits and pieces on your own computer.

Prototype Site

The https://proto.priv.evolveum.com/ site is dedicated for development and testing. The site will be automatically updated from the proto branch of docs and webdesign projects. I.e. when you push changes to the proto branch, the changes will be applied to the proto site instead of production site.

It is OK if you break the proto site, as long as you can fix it quite quickly (in few hours or days). The site is dedicated to experiments and testing. Just please do not leave unfinished code on proto branch. We do not want to accidentally merge the changes to master branch. It is OK to work on proto branch for couple of days. It is OK to commit frequently. But when you are done, either finish your work and merge it to master, or delete your code. Or maybe move your unfinished work to another branch. Just make sure that you leave proto branch clean when you are done (i.e. the same sa master).

Jekyll Yourself

You can install Ruby, Jekyll and all the Evolveum themes and plugins on your computer. Linux works best, but this may be possible on Windows as well. When you install this on your computer, you will be free to make any experiments you want.

This is how you install Jekyll environment on your Ubuntu:

Install Ruby environment (root):

sudo apt-get install ruby-full build-essential zlib1g-dev

Setup local ruby environment for your account

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Install Jekyll and Bundler as Ruby Gems

gem install jekyll bundler

This will install jekyll and bundler gems in your home directory (~/gems/). Bundler is a tool that manages dependencies of Ruby projects. Later on, bundler will automatically download all the public gems needed by our sites. Bundler will also keep them updated.

Clone evolveum-jekyll project from github. This project contains components needed for our sites, such as Evolevum Jekyll plugin and theme. These are not published as public gems, therefore they need to be installed manually.

git clone https://github.com/Evolveum/evolveum-jekyll.git

Build and install Evolveum gems. For easier marging to the master branch you can use --local option with the ./build.sh script. With this option it is going to write _configLocal.yml file to your home directory. When using this option, docs directory is going to be $HOME/docs, midpoint directories will be $HOME/mp-* and samples directory is going to be $HOME/mp-samples. When you want to change names or paths to these directories please don’t select any options and edit evolveum-jekyll-theme/_config.yml file.

cd evolveum-jekyll
./build.sh

This will install evolveum-jekyll-plugin and evolveum-jekyll-theme gems in your home directory (~/gems/).

Clone the Jekyll project from github:

git clone https://github.com/Evolveum/docs.git

Go to the Jekyll site and install necessary gems using bundler. When you want to also run jekyll serve and not only build the site you must also enter bundle add webrick:

cd docs
bundle install

This needs to be done only once. The bundle install or bundle update may need to be repeated in case that dependencies of our sites change. You will see bundler error in that case, and bundler will most probably tell you to run bundle install or bundle update.

Build the site. When you used --local option in build.sh you must also add --config _config.yml,../_configLocal.yml to the end of this command:

bundle exec jekyll build

Resulting site will be placed in _site directory. You can open it in a browser. Or, even better, start a Jekyll server, similarily like with the build command you must add --config _config.yml,../_configLocal.yml to the end of this command:

bundle exec jekyll serve

Jekyll will run as HTTP server on port 4000. You can connect to it on localhost:

http://localhost:4000

The best approach to edit the site is to open the project in IntelliJ IDEA. Modify the files. While the Jekyll server is running (jekyll serve), it will detect changes in files and it will rebuild the site automatically. All you need is to reload the page in the browser.

How It Works

The site is built using Jekyll static site generator. The site is generated from Jekyll "sources" into static HTML files. There is no dynamic interpretation of HTTP requests. Everything has to be generated before the first request comes, including headers, footers, navigation and everything else.

Jekyll is written in Ruby. Ruby is interpreted scripting programming language that is mixing object-oriented paradigms with functional programming. It is quite a nice language. It is also very efficient: short code can do a lot of things. As Jekyll is written in Ruby, Jekyll extensions (plugins) are also written in Ruby.

Perhaps the most important plugin to Jekyll is Asciidoctor (in a form of Jekyll AsciiDoc plugin). Asciidoctor adds support for AsciiDoc text format, that is used for vast majority of our documents. Asciidoctor transparently converts AsciiDoc (*.adoc) documents to HTML when Jekyll site is built.

Jekyll is set up to use evolveum-jekyll-theme as its theme. The theme contains stylesheets (SASS), page layouts, fonts, icons, evolveum logo and anything else that is used on all our sites. The theme has file structure that is almost the same as Jekyll site structure.

The theme needs evolveum-jekyll-plugin to work. The plugin is a small piece of Ruby code that add some features to Jekyll. Evolveum plugin mostly adds navigation features.

Both the theme and the plugin are designed to be used as Ruby gems. There is a build.sh script that builds and installs the gems.

The use of the theme and the plugin is specified in _config.yml file in the site.

When our the site refers to page layout, that layout is taken from the theme, from _layouts directory. Out page layout file (_layouts/page.html) specifies the structure of pages on our sites. This layout contains Liquid tags to render navigational elements ({% breadcrumbs %}, {% navtree %}). These are custom Liquid tags that are implemented in evolveum-jekyll-plugin. The plugin is documented in plugin source code files.

Redirects

Jekyll generates the redirects as a series of Apache RewriteRule statements in .htaccess file. The code is in the jekyll-redirect-plugin.rb file in the evolveum-jekyll-plugin project.

Gotchas

Jekyll and Ruby create a very nice environment. Creating, maintaining and customizing the site is mostly very easy and elegant. However, there are some problems in the paradise:

Jekyll themes can contain only "design" files, such as CSS/SASS or images. It cannot contain "content" files. This limitation is hardcoded in Jekyll. This is a nice theory, to separate design and content. However, there are problems in practice. For example, the theme cannot contain sitemap files (sitemap.xml, sitemap.html), which are considered to be "content". Therefore the Evolveum Jekyll plugin contains a special plugin code that uses Jekyll::PageWithoutAFile mechanism to create sitemap pages anyway. It is so satisfying to do easy things the hard way.