Setting up Jekyll - the basics

Introduction

Since Octopress has been deprecated for pure use of Jekyll, I switched this blog to use Jekyll. See this post as a walkthrough on creating a functional blog via Jekyll (part 1). This is yet another collation of snippets I have found useful, as a reference for my future self - and perhaps others.

Starting off

You can find the installation instructions for Jekyll in the official documentation .

After you install the Jekyll gem, scaffolding a new site is as easy as

Bash
1
jekyll new blog_name

This will create a new folder with a starter site. To serve your site to preview it, run the

Bash
1
jekyll --serve

command and navigate to http://localhost:4000 (the default port) with your favourite browser.

Defaults, excerpts and URL structures

By default the home page will display the full list of posts with all it’s glorious content. This might be a bit too much for longer posts. To enable excerpts with links to the full post you need to configure the excerpt_seperator. You can specify this in the front matter of each post. We can also specify the format of the permalink to the posts, with a sane URL structure including the date and title of the post.

Instead of repeating ourselves in the frontmatter of each post we can DRY it up a bit by specifying defaults in the config.yml file:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
defaults:
-
  scope:
      path: "" # an empty string here means all files in the project
      type: "posts" # previously `post` in Jekyll 2.2.
  values:
      layout: "post"
      excerpt_separator: "<!`--` more `--`>"
      comments: true
      permalink: "/blog/:year/:month/:day/:title"

The format YYmmDD is locale specific - but one advantage with using this format is that your posts can be chronologically ordered even on the file system. The final URL for a post would look something like this:

HTML
1
http://riaanhanekom.com/2018/01/21/travis-with-sonarcloud

With the configuration above applied, content displays on the home page up to where the content processor finds the  marker:

Override the look and feel

We can create a main stylesheet in the assets directory in your source folder. main.scss will be the Sass file included after everything else so you can override any styles that you want. Since we’ve used the minima theme it’s important that we import it at the top. Let’s put in a separator between the posts:

SCSS
1
2
3
4
5
6
7
@import "minima";

.post-list>li {
  border-bottom: 1px solid #b6b6b6;
  padding-bottom: 30px;
  margin:  10px 0px 30px 0px;
}

I’m not a big fan of the 800px fixed-width style - by adding the following CSS into assets/main.scss we can take up more real-estate on the screen:

CSS
1
2
3
4
5
6
7
.wrapper {
  max-width: none;
  margin-right: auto;
  margin-left: auto;
  padding-right: 10%;
  padding-left: 10%;
}

To override the markup provided by the default theme you can “eject”, copy the files from the gem installation directory into your own source directory and change them at will.

The command

Bash
1
bundle show minima

will show you the source directory to copy the files from.

Productionise it

As with any software development it’s important to get the production aspects out of the way. You can always change this later, but doing this early in the process avoids a bunch of “whoops, didn’t think about that” moments. Deploying to GitHub pages is a popular method of serving a blog made with Jekyll, but since I’ll be deploying this on a private server we’ll focus on building and running a docker container for this purpose. Let’s create a simple NGINX server to host our application with this Dockerfile:

Dockerfile
1
2
3
4
FROM nginx
COPY ./_site /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
COPY default.conf /etc/nginx/conf.d/default.conf

Simple enough. Jekyll generates the site static content under the _site directory which can we can copy into the default serving directory of NGINX. I’ve added a configuration file to add cache control headers for static content (images, js, css). HTML pages are still set for the browser to check back to server if any content has changed. We also enable gzip and set up NGINX to scan for the index.html file in directories to have nice file-less URLs:

Nginx
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
user  nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    server {
      location / {
        try_files $uri $uri/index.html $uri.html =404;
      }

      location /assets {
       expires 1M;
       add_header Cache-Control "public, max-age=691200, s-maxage=691200";
      }

      location /images {
       expires 1M;
       add_header Cache-Control "public, max-age=691200, s-maxage=691200";
      }
      rewrite ^/(.*)/$ /$1 permanent;
      expires $expires;
    }

    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;
    sendfile        on;
    keepalive_timeout  65;
    gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

At this point don’t forget to update the header include template to add a cache buster for the stylesheet:

HTML
1
<link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}?{{site.time | date: '%s%N'}}">

The generated link to the stylesheet would look something like /assets/main.css?1519308247603964426. The time value at the point of generation gets appended to the stylesheet URL allowing us to cache the asset on clients until it changes.

Working with drafts

To work on draft posts without publishing them, create a ‘drafts’ folder in your source folder per the documentation . When running jekyll serve, pass in the –draft parameter to show drafts. Depending on your needs it might also be useful to add the –future parameter to display posts that have a date in the future.

Paging

No good blog should be without paging. By default my installation came with the jekyll-paginate gem installed. I’ve found that the next iteration of the gem, jekyll-paginate-v2 works better and is simpler to set up.

To activate, add the jekyll-paginate-v2 to the plugins section of the config and your Gemfile. There are tons of configuration options for pagination, but here were the ones I found important for now:

YAML
1
2
3
4
5
pagination:
  enabled: true
  collection: 'posts'
  per_page: 8
  permalink: '/page/:num/'

Where you display your posts you will need to iterate over the paginator.posts instead of posts:

Ruby
1
for post in paginator.posts

If you are using the minima theme, it’s time to copy over the home.html file from the layouts folder and update it. We also shouldn’t forget to add the pagination links at the bottom:

HTML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{% if paginator.total_pages > 1 %}
<ul>
  {% if paginator.previous_page %}
 <li>
    <a href="{{ paginator.previous_page_path | prepend: site.baseurl }}">Newer</a>
 </li>
  {% endif %}
  {% if paginator.next_page %}
    <li>
      <a href="{{ paginator.next_page_path | prepend: site.baseurl }}">Older</a>
    </li>
  {% endif %}
</ul>
{% endif %}