Getting Started with Jekyll Blog

Updated: March 11, 2021

Initially, I tried to create a blog using the Remote Theme feature, but there seemed to be limitations in changing settings and potential vulnerability to version changes. So I decided to download the latest release and maintain the blog myself. This post was originally about how to change settings in remote theme state, but it has been modified to cover everything from starting a blog to changing settings.

Getting Started

The first thing to do is create a repository for your blog on Github. Create a repository following the rule {github id}.github.io and upload blog template files and post files - this will form the basis of your blog. To modify files locally, you can clone the repository to your local machine.

git init
git clone https://github.com/{id}/{id}.github.io

Installing Ruby

With Github blog, since it goes through the process of local modification - upload - Github update - homepage modification, it’s difficult to immediately check the results of modifications on the blog. The solution is to set up an environment to serve the blog locally so you can check changes immediately.

The installation process differs depending on whether you’re on Windows, MacOS, or Linux environment. I installed it on MacOS Big Sur 11.2.2. First, you need to install command line tools.

xcode-select --install

Jekyll requires Ruby version 2.4.0 or higher, and MacOS comes with Ruby 2.6.3 pre-installed since Catalina 10.15, so you can skip Ruby installation. However, if you’re using an earlier version of MacOS, you can install it using Homebrew.

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

brew install ruby

Then you need to add Ruby’s path to environment variables. Add it to .zshrc, .bashrc, .bash_profile etc. depending on your environment.

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.bash_profile

Check Ruby configuration.

which ruby
# /Users/statphy/.rbenv/shims/ruby (after rbenv setup is complete)

ruby -v
# ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin20]

Using rbenv

There’s also a method to use rbenv which is useful for managing multiple Ruby versions.

# Install rbenv and ruby-build
brew install rbenv

# Configure shell environment to integrate with rbenv
rbenv init

Add rbenv PATH to your shell configuration file (.zshrc, .bashrc, .bash_profile …) by adding the following code:

# Inside .bash_profile 

[[ -d ~/.rbenv  ]] && \
  export PATH=${HOME}/.rbenv/bin:${PATH} && \
  eval "$(rbenv init -)"

Then load these settings.

source ~/.bash_profile

Now you can install specific Ruby versions and configure them as needed. You can change global, local, shell settings according to your needs.

rbenv install 3.0.0
rbenv global 3.0.0
ruby -v
# ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin20]

The reason for introducing rbenv in this post is not for version management, but because when installing bundler and jekyll in the next step, using system ruby might cause permission errors. If you install and connect a new ruby, you can proceed with the steps below without permission issues.

Installing Bundler and Jekyll

Now you can install Bundler and Jekyll to serve your blog locally.

gem install --user-install bundler jekyll

Then add the following path to environment variables, replacing X.X with the first two numbers of your installed Ruby version.

echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

Checking Local Server

Now you can check your blog server locally with the following command:

bundle exec jekyll serve

However, if you installed Ruby version 3.0 or later, you might get a LoadError at this step. This is because webrick, which is needed for jekyll, is missing from that version. So add it and run again:

bundle add webrick

Changing Detailed Settings

Now it’s time to change specific aspects like theme, font, font size, highlight colors, letter spacing, line spacing, text alignment, etc.

Changing Theme

You can choose one of the themes provided by Minimal Mistakes. Initially, I used the dark theme because I liked dark themes, but headers and highlights weren’t very visible and it was difficult to add colors to text, so I switched to dirt. To change the theme, modify the _config.yml file as follows:

... in _config.yml file
minimal_mistakes_skin: "dirt"
...

If you’re using remote theme and theme files aren’t loading properly, errors might occur during this process. In that case, get the assets/css/main.scss file and modify it with the following code:

... in main.scss file
@import "minimal-mistakes/skins/dirt"; // skin

Changing Theme Color Palette

While the default colors of the Dirt theme are good, I personally like the solarized-light palette and want to change the code block colors and Footer background color. The file to modify is _sass/minimal-mistakes/skins/_dirt.scss. (For remote theme, you might be able to change colors by modifying variable values through assets/css/main.scss created earlier, but I haven’t verified this.)

First, let’s change the page Footer color and border color. The background color code for Solarized-Light is #eee8d5. This color is too bright for borders, so I set $border-color to a slightly darker #e7dfca. It’s good to keep the original definitions in comments for easy reversal.

... in _dirt.scss file

$border-color: #e7dfca !default;
$footer-background-color: #eee8d5 !default;
...

Changing Code Block Highlight

Next is how to change Code block Highlight. This also involves modifying the same file _sass/minimal-mistakes/skins/_dirt.scss. The basic Solarized color palette can be found here, but I wasn’t fully satisfied with it so I made some modifications. (Actually, the issue is that I’m not happy with the code highlighting provided by Markdown, but it would be difficult to find satisfactory color arrangements for all languages by modifying each one.)

$base00: #fdf6e3 !default;    /* Background */
$base01: #073642 !default;    /* Meaningless */
$base02: #586e75 !default;    /* Meaningless */
$base03: #657b83 !default;    /* Meaningless */
$base04: #93a1a1 !default;    /* Comment */
$base05: #657b83 !default;    /* Body Contents */
$base06: #eee8d5 !default;    /* Meaningless */
$base07: #fdf6e3 !default;    /* Meaningless */
$base08: #dc322f !default;    /* red */
$base09: #cb4b16 !default;    /* Meaningless orange */
$base0a: #b58900 !default;    /*  yellow  */
$base0b: #2aa198 !default;    /*  cyan  */
$base0c: #268bd2 !default;    /*  blue  */
$base0d: #859900 !default;    /*  green  */
$base0e: #6c71c4 !default;    /*  violet  */
$base0f: #d33682 !default;    /* magenta */

As a result, code blocks now appear in the following format:

'''

master equation of the system without stagnation is far easier than with finite stagnation.
Here we use simple diagonalization method, compute the solution of master equation

'''

from math import log
import numpy
from scipy import linalg

def master_eq(N, r):
    # N : number of particle at time zero
    # r : merging rate / searching rate

    def a(n, r):
        return n * (n + 1) * r / 2

    matrix = numpy.zeros((N, N))
    for i in range(N - 1, -1, -1):
        x = a(i , r)
        matrix[i, i] -= x + i + 1
        matrix[i - 1, i] += x

    return matrix

Changing Fonts

Font changes can basically be made by directly modifying _variable.scss or _reset.scss in the _sass folder. However, this method is not recommended as it can conflict with other settings, and other methods are suggested. The alternative method is to add the following code to the assets/css/main.scss file. Since this method changes the variable values in the imported minimal_mistakes code, add it after the @import "minimal-mistakes"; line.

... at bottom of main.scss file
$sans-serif: 'Noto Sans KR';
$monospace: 'Ubuntu Mono';
$type-size-4-5: 1.15em !default; // Ubuntu Mono is a bit small

@import url(https://fonts.googleapis.com/css?family=Noto+Sans+KR|Ubuntu+Mono);

The meaning of each line is simple. The first and second lines change the font variables defined throughout the theme to our desired Noto Sans KR and Ubuntu Mono, and the last line means we’ll get the font information from Google fonts. The third line is code I borrowed from a reference blog - when using Ubuntu Mono as is, all text in inline code or code blocks becomes too small, so it seems they slightly increased the size to match.

Changing Font Size

Next is changing font size. This can also be modified by editing the assets/css/main.scss file.

... in main.scss file
html {
  font-size: 12px; // change to whatever

  @include breakpoint($medium) {
    font-size: 14px; // change to whatever
  }

  @include breakpoint($large) {
    font-size: 16px; // change to whatever
  }

  @include breakpoint($x-large) {
    font-size: 16px; // change to whatever
  }
}

You can freely choose font sizes from smallest to x-large. (If I understand correctly) This sets the base values for responsive site font sizes. The original x-large value was set to 18px, but I reduced it to 16px as it seemed too large.

Changing Text Background Color

When writing inline code, text is emphasized with a background color. In the Dirt theme, this background color is white, which isn’t very readable. I wanted to change it to light gray (#e4e6e7). Add the following code to the bottom of the assets/css/main.scss file:

... in main.scss file
.language-plaintext {
  font-family: $monospace;
  font-size: $type-size-5;
  background: #e4e6e7;
}

Changing Text Alignment

I prefer text to be justified even if words are cut off. So I changed the settings for justified text alignment:

... in main.scss file

.page__content {
  text-align: justify;
}

.sidebar__right {
  text-align: left;
}

Here, justify means justified alignment. If you only change .page_content, (though this blog doesn’t have it) the sidebar text format sometimes appears strange. To prevent such cases, I set .sidebar__right to be left-aligned.

Adding Table of Contents

Minimal Mistakes can display a Table of Contents for articles in the sidebar. Basic instructions can be found here. You can add the following code to the front matter where you write title, date, etc. at the beginning of the post markdown file to display ToC:

... in post's front matter yaml code section

toc: true
toc_label: "Table of Contents"
toc_icon: "fas fa-clipboard-list"
toc_sticky: true

The "fas fa-clipboard-list" used in the toc_icon section can use icons from the Font Awesome site. The toc_sticky item determines whether the toc should stick and follow the screen - I like this feature so I set it to true.

Creating Favicon

A favicon is the icon that appears next to the tab title when opening a page in a browser. If you created your homepage by just extracting the release file, you might get a warning about missing favicon.ico. So this blog uses . You can find sites that create icons for free or distribute pre-made ones for free - just choose one and put it in the outermost directory of your repository for it to be recognized.

Share on

Twitter Facebook LinkedIn

Myeongseon Choi