First thing: Jekyll is a static website framework which is useful for building a blog. Jekyll is build by ruby and need to use gem as a package management.
FYI: most of the content of the blog is based on the Mike Dane Youtube Channel.
1. Installation and Basic Stuff
Installation steps
Environent: What I choose is using a ruby version manager chruby and ruby-install to aviod change the Opearting system’s ruby version. Details
1
2
3
brew install chruby ruby-install
ruby-install ruby
chruby 3.1.0 # change ruby version
- Command to new a website:
Jekyll new <website-name>. - First time to run the server,
bundle execis a command to execute a script(Gemfile) in the context of the current bundle and change the golbal package version to the specific version in the Gemfile. - Use
jekyll serveto run the server.
Framework Architecture
After build the website, some key files of the website is like the following items.
- _posts: save the blogs.
- _layouts: set the layout of interface.
- _site: save all the builded static website. Do not need to modify it.
- _drafts: save the drafts which do not want to be public. But using
jekyll serve --draftwill display these drafts in the website. - _config.yml: set the global variables and need to restart the jekyll server to implement the change in the file.
- Gemfile: set the gem package version.
The blogs written in markdown in the /_posts path are consisted of two parts: front matter and content.
- Front matter: written in JSON or YAML. Including layout, title, date, categories and so on. And Jekyll will use these variable to set the url of the blog. Besides, custom variable can be added as well.
- Content: the main ideas of blogs.
The sample of the front matter is like that:
1
2
3
4
5
6
7
---
layout: post/page
title: "Welcome to Jekyll!"
date: 2020-02-03 15:38:48 +0800
categories: jekyll update
permalinks: /about/
---
We can set default front matter on _config.yml.
1
2
3
4
5
6
7
8
defaults:
-
scope:
path: ""
type: "posts"
values:
layout: "post"
title: "my title"
Hint: If we edit the _config.yml file, we need to restart the jekyll server to see the change on the website.
2. Building Your Website
2.1 Choose a theme
The quickest way to choose a theme has two steps:
(1) Set the theme name on the _config.yml file by theme: minimal-mistakes-jekyll
(2) Edit Gemfile to install the related packages: gem "minimal-mistakes-jekyll"
2.2 Layout
Also, we can set custom layout by building a layout.html file under the folder _layout.
In the layout.html, we can use HTML and Liquid.
In the file, content can be used to display the markdown part.
2.3 Varibale
We can use _include folder to save header.html and footer.html.
And we can also use site.title and other variable like site.message to use the information form _config.yml.
Besides, we can use
1
2
3
{% include header.html color%}
to cite the header.html file to another file. The variable color can be set in the header.html file by include.color as well.
Let’s take an example.
In the header.html:
1
2
<h1 style="color: {{include.color}}">{{site.title}}</h1>
<hr></hr>
In the other files, if we want to cite the header.html file, and loop the variable, the example is like that.
<html>
<head>
<meta charset="UTF-8">
<title>{{site.title}}</title>
<head>
<body>
{% include header.html color="blue" %}
{{ content }}
# loop
{% for post in site.posts %}
{{ post.title }} <br>
{% endfor%}
# conditional
{% if page.title == "My First Post" %}
This is the first post.
{% elsif page.title == "My Second Post "%}
This is the second post.
{% else %}
This is another post.
{% endif %}
</body>
</html>
2.4 Files
We can create_data folder to store data files to save all source of information. We can use yml, json or csv. And the way we cite the data is by site.data.column.
Another file we can use in Jekyll is static file such as images and pdf by site.static_files and use file.path or file.name to describe these files.
If we want to use images in a specific path, we can set the default settings in _config.yml.
1
2
3
4
5
6
defaults:
-
scope:
path: "images/img"
values:
image: true
And then we can use these images in the other files direcitly.
1
2
3
4
5
{% for file in site.static_files %}
{% if file.image %}
<img src="{{file.path}}" alt="{file.name}">
{% endif %}
{% endofor %}
3. Hosting on Github Pages
First Step: Create a new repository on Github.
Second Step: Set base url or domain name in _config.yml
Third Step: set the Jekyll website and sync the github repository.
1
2
3
4
5
6
7
git init
git checkout -b repo
git status
git add .
git commit -m "initial commit"
git remote add origin https://github.... # your github repo path
git push origin repo
Fourth Step: Set your repo github pages on the settings.
More information about github pages is available here.
Jekyll-related Problem Recording
1. Busuanzi Counting Prblem
busuanzi is a pretty straightforward and easy-using script for website to count the page views. While the single page counter seems not to work incorrectly. I have tried on my own website and visit several other websites on the Internet. It shows that the single page counter just show all pages viewing number instead of separating them.
1
2
3
<span id="busuanzi_container_page_pv" style='display:none'>
Read: <span id="busuanzi_value_page_pv"></span> Times
</span>