The following are useful websites for learning jekyll:

  • Jekyllrb Official: https://jekyllrb.com/
  • Github Page: https://docs.github.com/en/pages/quickstart

Install Jekyll

To install jekyll on Macos, we will first use brew to install a separate ruby, e.g., ruby@3. Macos has a built-in ruby installed, but we will need root priviliege to install packages, i.e., running ruby commands with sudo, it’s not safe so we won’t do that.

brew install ruby@3

After the installation, we export the path to ruby@3. Of course we can run brew link, but it won’t work because there is already one pre-installed. If you run brew link, you will see the warning messages.

Warning: Refusing to link macOS provided/shadowed software: ruby
If you need to have ruby first in your PATH, run:
  echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.profile

# ...

We can follow it’s recommendation, we export the path in our ~/.profile file or ~/.bashrc file.

export PATH="/usr/local/opt/ruby/bin:$PATH"

Til this point, ruby@3 is successfully installed. You may setup a mirror registry like the following to speed things up a bit. Usually you don’t need to change the sources, unless you are from certain countries like me.

# setup mirror source for gem
gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/ --remove https://rubygems.org/

Then, we will also need to install bundle, which is a dependency manager for ruby (kinda). Then we install jekyll, the package that we need.

gem install bundler jekyll

We can also setup the source address for bundle, it’s completely optional.

bundle config mirror.https://rubygems.org https://mirrors.tuna.tsinghua.edu.cn/rubygems

Then we can start following the tutorial and create our first jekyll project.

jekyll new my-awesome-site

We can cd into it, and serve the website in dev mode.

bundle exec jekyll serve

In the meantime, if you are using ruby@3 like me, for whatever reason, you may see a warning message as follows. I don’t really know what causes it, but it seems like jekyll is actually working fine. I personally believes that it’s related to the version of our dependencies, some stuff may be deprecated.

Deprecation Warning: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.

Recommendation: math.div($spacing-unit, 2) or calc($spacing-unit / 2)

More info and automated migrator: https://sass-lang.com/d/slash-div

   ╷
40 │   margin-bottom: $spacing-unit / 2;
   │                  ^^^^^^^^^^^^^^^^^
   ╵
    ../../../../minima-2.5.1/_sass/minima/_base.scss 40:18  @import
    minima.scss 48:3                                        @import

Lukily, I did find a way to fix it (by muting the warning messages).

Inside _config.yml, we add the following properties:

sass:
  quiet_deps: true

Run jekyll serve again, we will see our website on http://localhost:4000.

The Basic

By default jekyll uses theme minima, you are free to change it.

A jekyll project contains multiple _*** directories. The _posts directory store the posts you write. The _site directory stores the static files generated by jekyll, so you will not modify files in this directory.

File _config.yml includes the basic configuration for your jekyll website. There are also the about.markdown and index.markdown files in root directory, you can modify the content of these two files as well as the markdown files in _posts.

Once you have done writing the content, you can run jekyll serve to see the latest changes. All the changes are rendered and written to _site directory.

In most of the cases, you will be modifing files inside _posts directory. The filename must follow the following convension: YEAR-MONTH-DAY-title.MARKUP, or else the posts are not displayed on webpage.

e.g.,

2024-04-01-learning-go.markdown
2024-04-02-learning-js.markdown
2024-04-03-learning-java.markdown

To better understand the file hierarchy, the following is the file tree of a demo project.

.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   ├── 2024-04-15-learning-jekyll.markdown
├── _site
│   ├── ...
├── about.markdown
└── index.markdown

If we want to create a new post, we can just simply copy the existing post file in _posts, modify the content and that’s it.

E.g., a new file named 2024-04-15-my-first-blog.markdown.

---
layout: post
title:  "My First Blog"
date:   2024-04-15 13:00:00 +0800
categories: random stuff
published: true
---

I am the first blog!

That’s it. This should be enough to get started.

Host Jekyll Project Using Github Page

Follow guidelines in https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll.

Before you push all the changes to upstream, build the jekyll project as follows:

bundle exec jekyll build

Go to github page, in repo’s Settings > Pages, select your branch and root directory, and then save. The github page for your jekyll project will be deployed automatically using github action.