Notes on Jekyll 4.0

Today, I went through my instructions here and I got some problems due to new Jekyll 4.0.0 version. After some searches, I found following notes to solve the problem:

  • It seems that the current github-pages is not compatible with Jekyll 4.0.0. So in the section, I mentioned the version of jekyll and bundle explicitly.
  • After calling bundle install, I got a weired error for nokogiri gem. Due to link, I installed zlib1g-dev package in my Debian box, so the error is resolved.

Creating a Simple Blog Site

What you need:

  • A GitHub account
    • A repository with the name of <USERNAME>.github.io
    • A pushed project of Jekyll
  • A DNS name for your blog (Optional): More Info

Installation (Ubuntu/Debian)

The main installation guide: Jekyll Site

1

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

1
2
3
4
5
6
7
8
9

echo 'export GEM_HOME=$HOME/App/Gems' >> ~/.bashrc
echo 'export PATH=$GEM_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
gem install jekyll -v '3.8.2'    # - Installing jekyll via Ruby Gems
gem install bundler -v '1.16.2'  # - Installing bundler via Ruby Gems
jekyll -v                        # - My Version: 3.8.2
jekyll new myblog                # - Create a project based on Minema template
cd myblog
bundle exec jekyll serve         # - Build & Execute a local web server

The last command starts a local webserver with address http://127.0.0.1:4000 to review the blog. To stop it, just press ctrl+c.

The contents in folder myblog are:

  • _posts/
  • _config.yml
  • .gitignore
  • 404.html
  • about.md
  • Gemfile
  • Gemfile.lock
  • index.md

On Ruby Update

There are times when you update your system and ruby packages, and your gems won’t work anymore. In that case execute following commands in root of your project to reinstall your required gems:

1
2

gem install bundler -v '1.16.2'
bundler install

Configuration

Enable Github Pages

  • Modify Gemfile to enable github-pages (instructions included in the file)
  • Execute bundle update
  • If you encounter version incompatibility with Jekyll 4 or about nokogiri, refer to link

Preferred Setting

File _config.yml is the configuration of the site based on YAML format (mostly key: value pairs). Preferred altered config entries are:

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

title: <SITE TITLE>
email: <EMAIL>
description: <DESCRIPTION>
author: <DEFAULT_SITE_AUTHOR>

url: "<DNS_URL_NAME or <USERNAME>.github.io>"
permalink: /:categories/:title
show_excerpts: true

github_username: <G_USERNAME>
twitter_username: <T_USERNAME>
linkedin_username: <L_USERNAME>

markdown: kramdown
kramdown:
  syntax_highlighter_opts:
    block:
      line_numbers: true
theme: minima
plugins:
  - jekyll-feed

defaults:
  -
    scope:
      path: ""
      type: posts
    values:
      author: <DEFAULT_BLOG_ENTRIES_AUTHOR>

Note: Lines from 15 to 18 is set to show line numbers generally in all code blocks.

Style Customization

Since showing line numbers is set in the _config.yml, the rendered result is not well and needs to be altered. So the main style of site must be modified. To handle this issue, the file <PRJ_DIR>/assets/main.scss must be created with following content:

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

---
# Only the main Sass file needs front matter (the dashes are enough)
---

$content-width: 1000px !default;

@import "minima";

.highlight {
  table {
    border: 0;
    margin: 0;

    th, td {
      padding: 0;
      border: 0;
    }
  }

  pre, code {
    border: 0;
    margin: 0;
    font-size: 14px;
  }
}
  • The highlight css class here overrides the default definition in minima theme.
  • Line 5 set the content width to 1000px. The variable is defined in file minima.scss in minima’s GEM directory ($GEM_HOME/gems/minima-2.4.1/_sass/minima.scss)

Create a Post

  • Must create a file in the _posts directory with name of pattern: <YEAR>-<MONTH>-<DAY>-<NAME>.md
  • Must starts the file with following content at top (called Front Matter): 
    1
2
3
4
5
6

    ---
layout: post
title: "<TITLE>"
categories: <CAT1> [, <CAT2>, ...]
excerpt: <EXCERPT> 
---
  • Now continute the content based on Markdown format

Create a Page

  • A page is a link that is shown at the top header of your blog (menu bar)
  • By default, an about.md page is created
  • To add a page, just create a <NAME>.md file in the root of your project with following content at top (called Front Matter): 
    1
2
3
4
5

    ---
layout: page
title: "<TITLE>"
permalink: /<LINK>/
---
  • Now continue the content based on Markdown format

Note: In my case, I created a pages directory in the root of the project, and I saved all my pages in it, even about.md. Jekyll automatically finds all the pages in all normal directory (not started with _) and generates them in the root of your blog.

Basics

  • After building the site, _site/ is created.
  • All regular files are copied to _site/, unless it starts with _.
  • After Gemfile modification, execute bundle update
  • For GitHub Pages Gem (set in Gemfile), execute apt install zlib1g-dev by root user
  • The default theme is minema
  • Execute bundle show minima in project root directory: it shows the home directory of theme gem minima (i.e. $GEM_HOME/gems/minima-2.4.1). In spite of older version, the following directories are in theme home directory:
    • _includes/
    • _layouts/
    • _sass/

    Note: you can copy any above directory to the site to change the default generation behavior.

Front Matter

  • The content between two --- at the above of an .md file.
  • It is in JSON or YAML format, each row is a key: value pair. In fact, they are meta-data for a post!

Post

  • Except the layout, other keys are optional! 
    1
2
3
4
5
6
7

    ---
layout: post
title: "<TITLE>"
date: <YEAR>-<MONTH>-<DAY> <HOUR>:<MINUTE>:<SECOND> <TIME_ZONE>
categories: <CAT1> [, <CAT2>, ...]
excerpt: <EXCERPT>
---

Page

  • Except the layout and title, other keys are optional! 
    1
2
3
4
5

    ---
layout: page
title: "<TITLE>"
permalink: /<LINK>/
---

Creating Drafts

Drafts are posts which has not been published yet. So they must be in another directory. Jekyll has a standard for it, and you can create _drafts in your repository’s root and put your drafts in it.

Note: To preview your drafts in your local environment, you can execute Jekyll by bundle exec jekyll serve --drafts.