Jekyll

#blog #cms #lang-ruby 

Jekyll is an easy to use static site generator that builds fast, blog-aware, responsive websites.

The website is created with markdown and Jekyll generates the html files and deploys it to the webserver. It is possible to connect Jekyll to git, so that the website can be created on a local machine and then pushed to git where it gets deployed automatically via git hooks.

Jekyll is written in Ruby and licensed under the MIT license.

Note

For this guide you should be familiar with the basic concepts of

License

All relevant legal information can be found here

Prerequisites

We’re using Ruby in the version 2.7.2:

[isabell@stardust ~]$ ruby -v
ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]
[isabell@stardust ~]$

Your domain needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

You need to install a gem called Jekyll:

[isabell@stardust ~]$ gem install bundler jekyll
Fetching bundler-2.2.19.gem
WARNING:  You don't have /home/isabell/.local/share/gem/ruby/2.7.0/bin in your PATH,
         gem executables will not run.
[...]
Building native extensions. This could take a while...
[...]
Successfully installed jekyll-4.2.0
27 gems installed
[isabell@stardust ~]$

You can ignore the warning regarding your PATH.

Installation

Jekyll is a ruby gem that creates dummy files and directories for us that contain your website. We can modify these files to make your website look like we want it to.

Just let Jekyll create a new folder containing your website by typing:

[isabell@stardust ~]$ jekyll new website
Running bundle install in /home/isabell/website...
[...]
New jekyll site installed in /home/isabell/website.
[isabell@stardust ~]$

After Jekyll finished, navigate into your website folder.

Set the local path for bundler, then install all needed gems for your website:

[isabell@stardust ~]$ cd ~/website
[isabell@stardust website]$ bundle config set --local path 'vendor/bundle'
[isabell@stardust website]$ bundle install
[...]
Bundle complete! 6 Gemfile dependencies, 31 gems now installed.
Bundled gems are installed into `./vendor/bundle`
[...]

[isabell@stardust website]$

Now you can build and deploy your website to your document root:

[isabell@stardust website]$ bundle exec jekyll build --destination ~/html

Configuration file: /home/isabell/website/_config.yml
            Source: /home/isabell/website
       Destination: /home/isabell/html
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 0.919 seconds.
 Auto-regeneration: disabled. Use --watch to enable.
[isabell@stardust website]$

We need to tell Jekyll in what folder to build the website. Since we want it to appear in our document root, we have to add a configuration for the build process:

  • --destination: Tells Jekyll where to build the website (here ~/html).

Finishing installation

Now open a browser and navigate to your URL where you can see your beautiful responsive website.

Best practices

If you don’t want to create and modify your website on your uberspace, you can install Ruby, Jekyll and git on your local machine and then push it to your uberspace where it gets deployed automatically. This is an easy way to work with an editor of your choice and you can test your website before publishing it.

To install Ruby, Windows users should use RubyInstaller, Linux and Mac users could use RVM.

On your uberspace, create a folder, enter it and initialize a bare git repository.

[isabell@stardust ~]$ mkdir ~/website
[isabell@stardust website]$ cd ~/website
[isabell@stardust website]$ git init --bare
Initialized empty Git repository in /home/isabell/website/
[isabell@stardust website]$

Since we just need an empty repository to upload our website to, we need to add an option for initializing a repository:

  • --bare: Creates an empty repository for sharing.

Clone that repository on your local machine, enter the parent folder and create a new website by typing:

[user@localhost ~]$ jekyll new website --force
[user@localhost ~]$

Note

By entering the parent folder and using the same name for your website as the cloned repository you can create the website directly inside the repository folder. If you give your website a different name, you have to copy your website into your repository.

After Jekyll created the website you can enter it and run the local webserver for testing:

[user@localhost ~]$ cd website
[user@localhost website]$ bundle exec jekyll serve
[...]
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.

[user@localhost website]$

Now open a browser and navigate to http://127.0.0.1:4000 to see your website on your local machine.

The next thing we we want to do is creating a post-update rule in git to deploy our website automatically when pushing from our local machine to our remote repository.

Therefor we have to enter our remote repository and create a post-update hook file ~/website/hooks/post-update with the following content:

GIT_REPO=$HOME/website
TMP_GIT_CLONE=$(mktemp -d)
GEMFILE=$TMP_GIT_CLONE/Gemfile
PUBLIC_WWW=/var/www/virtual/$USER/html

git clone $GIT_REPO $TMP_GIT_CLONE
BUNDLE_GEMFILE=$GEMFILE bundle install --path vendor/bundle
BUNDLE_GEMFILE=$GEMFILE bundle exec jekyll build --source $TMP_GIT_CLONE --destination $PUBLIC_WWW
rm -Rf $TMP_GIT_CLONE

Note

If needed, PUBLIC_WWW can be adapted to serve on a different domain.

We need to tell Jekyll where to find the source files of the website and where to deploy. So we have to add a configuration for the build process:

  • --source: Tells Jekyll where to find the source of the website (here $TMP_GIT_CLONE).

  • --destination: Tells Jekyll where to build the website (here $PUBLIC_WWW).

All we have to do now is to commit and push from our local to our remote repository. The remote git will now clone the website on your uberspace, build it with Jekyll and deploy the website in your document root. After deploying, the cloned repository will be deleted, because it is not needed anymore.

Tuning

For further information about creating pages, posts or using themes, go to https://jekyllrb.com/docs/

Updates

Since Jekyll is a ruby gem, you can update Jekyll and every gem needed by your website by entering your website folder and typing:

[isabell@stardust ~]$ cd website
[isabell@stardust website]$ bundle update
[...]
Bundle updated!
[isabell@stardust website]$

Tested with Ruby 2.7.2, Jekyll 4.2.0, Uberspace 7.10.0

Written by: Pascal Nowak <pascal@nowak.app>