Jekyll + Liquid

This note is used for you who have already had the basic idea about jekyll and how to create a jekyll site. This note is only for quickly reference.

Using docker to run/deploy jekyll #

Read this readme. An example is an old version of this site.

Install and run Jekyll on fresh machine #

MacOS #

This tut is for macOS 11.0 Big Sur.

# install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew --version # check version
# install rbenv to mange ruby versions
brew install rbenv ruby-build
# add rbenv to bash
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.zshrc
source ~/.zshrc # refresh bash
# install ruby
rbenv install 3.0.0
rbenv global 3.0.0
# reload the terminal / sessions
ruby -v
# go to some jekyll source codes
install bundler
gem install bundler

# install gems
bundle config set --local path 'vendor/bundle'
bundle install

# serve
bundle exec jekyll serve

Ubuntu #

Install rvm (ruby version manager)

Check this main repo.

sudo apt-get install software-properties-common
sudo apt-add-repository -y ppa:rael-gc/rvm
sudo apt-get update
sudo apt-get install rvm

# add user to group
sudo usermod -a -G rvm thi

# Open terminal setting > tick on "Run command as a login shell"

# Reboot

# Enable local gemsets
rvm user gemsets

# install newest ruby
rvm install ruby

# use system
rvm use system
# use custom rvm
rvm use 3.0.0

# relaunch terminal
# install ruby using rvm
rvm install 3.0.0
rvm --default use 3.0.0

# install bundler
sudo gem install bundler
# clone a jekyll theme
# cd to that theme

# install gems in the theme
bundle install --path vendor/bundle
# serve
bundle exec jekyll serve

# If error "ExecJS and could not find a JavaScript runtime"
sudo apt-get install nodejs

Windows #

Follow this guide using WSL2 on Windows.

Make jekyll build faster #

# BENCHMARKING your site
bundle exec jekyll build --profile
# clean cache
bundle exec jekyll clean
  1. Disable jekyll-feed
  2. Run bundle exec jekyll serve -I (wuth -I) to generate the changed file only. If you create a new file, open a new terminal tab and run bundle exec jekyll build.
  3. Upgrade to Jekyll 4.0.
  4. Add gem "liquid-c" to Gemfile and make bundle update
  5. Use jekyll-include-cache (both in Gemfile and _config.yml)

Read more in this article.

Disable jekyll-feed #

  1. Comment line jekyll-feed in Gemfile
  2. Comment line jekyll-feed in _config.yml
  3. Rebuild.

Sitemap #

If in sitemap, there is error like <loc>/reading</loc>, check your _config.yml + make sure there is an url inside url field.

Loop through posts #

{% for post in site.posts %}
{{ post.title }}
{% endfor %}

If you using baseurl,

# in _config.yml
url: ""
baseurl: "/tools"
<ol>
{% for post in site.posts %}
<li>
<a href="{{ site.baseurl }}{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ol>

List all posts in each category,

{% for category in site.data.categories %}
{% if site.categories[category.name].size > 0 %}
{% for post in site.categories[category.name] %}
{{ post.title }}
{% endfor %}
{% endif %}
{% endfor %}

List all posts in ABC order[ref],

{% assign sortedPosts = site.posts | sort: 'title' %}
{% for post in sortedPosts %}
{{ post.title }}
{% endfor %}

List of categories and tags in a single line with commas,

{% for category in site.categories reversed %}{% capture category_name %}{{ category | first }}{% endcapture %}<a href="{{site.url}}{{site.baseurl}}/#{{category_name | replace: " ","_"}}">{{ category_name }}</a>{% if forloop.length > 1 and forloop.last != true %}, {% else %}.{% endif %}{% endfor %}
{% for tag in site.tags %}{% capture test %}{{tag[0] | slice: 0}}{% endcapture %}{% capture testup %}{{tag[0] | slice: 0 | upcase}}{% endcapture %}<a href="#{{tag[0] | slugify}}{% if test == testup %}_cap{% endif %}">{{tag[0]}}</a>{% if forloop.length > 1 and forloop.last != true %}, {% else %}.{% endif %}{% endfor %}

Edit tags for all posts #

Read this source code.

Using markdown syntax inside html tags #

You can use directly by

<span markdown="span"></span>
<div markdown="1"></div>

of only once,

{::options parse_block_html="true" /}
<!-- other html + markdown inside -->

Or even shorter,

Testing {::nomarkdown}**see**{:/} and test.

Check version #

  • Local gems: gem list jekyll.
  • Current jekyll version of website: check Gemfile. Need to run bundle update if change any version in this file.
[Name of Link]({% post_url 2010-07-21-name-of-post %})

Edit this post on github (put below link in your post layout),

https://github.com/dinhanhthi/dinhanhthi.com/edit/master/{{path.path}}

Custom domain & repository with Jekyll sites #

There are several choices for you to choose, it depends on your need.

You don't have a custom domain #

  1. Suppose your github account is <username>.
  2. Create a repo <username>.github.io.
  3. Put your site in branch master (default).
  4. Your site is published at https://<username>.github.io

If you wanna store your site in a custom repo, e.g. mysite:

  1. Create a branch gh-pages + set it as default + store your site here.
  2. Remove content at url: in _config.yml.
  3. Your site is live at https://<username>.github.io/mysite/

You have a custom domain #

  1. Create file CNAME at root and put <customdomain>.com in it.
  2. Create A or CNAME record in DNS provider. Check more.
  3. You can also use netlify to set all things up automatically.

Using custom plugins? #

  1. Build your site locally and get a folder _site.
  2. Put it to github and see the results.

You can also use netlify, it accepts custom plugin as well.

Using _data with include #

You can use,

{% include proud-of.html data=site.data.proudof-notes %}

where there is a data file located in _data/proudof-notes.yml.

Create a custom tags/blocks #

Refs #

Tag with single parameter #

{% render_time page rendered at: %}
page rendered at: Tue June 22 23:38:47 –0500 2010

Inside folder _plugins, create a file thi_single_tag.rb whose content is,

module Jekyll
class RenderTimeTag < Liquid::Tag

def initialize(tag_name, text, tokens)
super
@text = text
end

def render(context)
"#{@text} #{Time.now}"
end
end
end

Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)

Tag with two parameters #

{% badge update | green %}
<span class="tbadge badge-green">update</span>

Inside folder _plugins, create a file thi_badge.rb whose content is,

class Badge < Liquid::Tag
def initialize(tag_name, input, tokens)
super
@input = input
end

def render(context)
# Split the input variable (omitting error checking)
input_split = split_params(@input)
text = input_split[0].strip
color = input_split[1].strip

# Write the output HTML string
output = <<~EOS
<span class="tbadge badge-#{color}">#{text}</span>
EOS


# Render it on the page by returning it
return output;
end

def split_params(params)
params.split("|")
end
end
Liquid::Template.register_tag('badge', Badge)

Block with single parameter #

For example, we wanna create a custom block alertbox using class from Bootstrap.

{% alertbox warning %}
Content
{% endalertbox %}
<div class="alert alert-warning" role="alert" markdown="1">
Content
</div>

Inside folder _plugins, create a file thi_alert.rb whose content is,

module Jekyll
class Alertbox < Liquid::Block
def initialize(tag_name, input, liquid_options)
super
@input = input.strip
end

def render(context)
content = super

case @input
when "warning"
box_type = 'warning'
when "success"
box_type = 'success'
when "primary"
box_type = 'primary'
when "secondary"
box_type = 'secondary'
when "danger"
box_type = 'danger'
when "info"
box_type = 'info'
when "light"
box_type = 'light'
when "dark"
box_type = 'dark'
end

output = <<~EOS
<div class="alert alert-#{box_type}" markdown="1">
#{content}
</div>
EOS

end
end
end

Liquid::Template.register_tag('alertbox', Jekyll::AlertBox)

Nested blocks with crossed-using variables #

A more complicated example, suppose that you wanna create a hide/show box using Bootstrap's Collapse, you can use below shortcode. Its advantage is that you don't have to put manually the id for each box! Wonderful!

{% hsbox %}

{% hstitle %}
Box's title
{% endhstitle %}

{% hscontent %}
Box's content.
{% endhscontent %}

{% endhsbox %}
<div class="hide-show-box">
<button type="button" markdown="1" class="btn collapsed box-button" data-toggle="collapse" data-target="#box1ct">
Box's title
</button>
<div id="box1ct" markdown="1" class="collapse multi-collapse box-content">
Box's content.
</div>
</div>

Inside folder _plugins, create a file thi_hideshowbox.rb whose content is,

module Jekyll
class HideShowBox < Liquid::Block

def initialize(tag_name, contain, tokens)
super
end

def generate_box_id(number)
charset = Array('A'..'Z') + Array('a'..'z')
Array.new(number) { charset.sample }.join
end

def render(context)
context.stack do
context["boxID"] = generate_box_id(20) # create the box's ID
@content = super
end
"<div class=\"hide-show-box\">#{@content}</div>"
end
end

class HSBtitle < Liquid::Tag
def initialize(tag_name, contain, tokens)
super
@title = contain
end

def render(context)
boxID = context["boxID"] # get the box's ID

output = <<~EOS
<button type="button" markdown="1" class="btn collapsed box-button" data-toggle="collapse" data-target="##{boxID}">#{@title}</button>
EOS

end
end

class HSBcontent < Liquid::Block
def initialize(tag_name, contain, tokens)
super
@showBox = contain.strip
end

def render(context)
boxID = context["boxID"] # get the box's ID
if @showBox == 'show'
classShow = 'show'
else
classShow = ''
end
output = <<~EOS
<div id="#{boxID}" markdown="1" class="collapse multi-collapse box-content #{classShow}">
#{super}
</div>
EOS


output
end
end
end

Liquid::Template.register_tag('hsbox', Jekyll::HideShowBox)
Liquid::Template.register_tag('hstitle', Jekyll::HSBtitle)
Liquid::Template.register_tag('hscontent', Jekyll::HSBcontent)

💡 Actually, there is a simpler solution for this task. We can get

{% hsbox **Box's title** | show %}
Box's content.
{% endhsbox %}
<div class="hide-show-box">
<button type="button" markdown="1" class="btn collapsed box-button" data-toggle="collapse" data-target="#something">
<strong>Box's title</strong>
</button>
<div id="something" markdown="1" class="collapse multi-collapse box-content">
Box's content.
</div>
</div>

by using

module Jekyll
class HideShowBox < Liquid::Block

def initialize(tag_name, contain, tokens)
super
@input = contain
end

def generate_box_id(number)
charset = Array('A'..'Z') + Array('a'..'z')
Array.new(number) { charset.sample }.join
end

def render(context)
# Split the input variable (omitting error checking)
input_split = split_params(@input)
title = input_split[0]
boxid = generate_box_id(20)
if input_split[1] != nil
if input_split[1].strip == 'show'
showbox = "show"
else
showbox = ""
end
else
showbox = ""
end
content = super

output = <<~EOS
<div class="hide-show-box">
<button type="button" markdown="1" class="btn collapsed box-button" data-toggle="collapse" data-target="##{boxid}">
#{title}
</button>
<div id="#{boxid}" markdown="1" class="collapse multi-collapse box-content #{showbox}">
#{content}
</div>
</div>
EOS

end

def split_params(params)
params.split("|")
end
end
end

Liquid::Template.register_tag('hsbox', Jekyll::HideShowBox)

Problem with kramdown #

Somtimes, we cannot use markdown="1" directly in ruby file. For example, below block of code produces a block of codes (<pre>) instead of a single text,

def initialize(tag_name, input, liquid_options)
super
@title = input
end

def render(context)
content = super
output = <<~EOS
<div class="def-box" id="dn1">
<div class="box-title" markdown="1">
#{@title}
</div>
<div class="box-content" markdown="1">
#{content}
</div>
</div>
EOS

end

Instead, we change a little bit like this,

<div class="box-title">
<span markdown="span">#{@title}</span>
</div>

Run with draft #

Inside the root folder, create a folder named _drafts. You can put your draft posts inside this folder and whenever you wanna show it in your site, use this command,

bundle exec jekyll serve --draft

In the case you have already build your site (all new posts are rendered to _site), you only changes some small things in some post and you don't want jekyll to render again all things on your site (just look at your current post), use this,

bundle exec jekyll serve -I

Serve in background #

# start
bundle exec jekyll serve 2>&1 &
bundle exec jekyll serve -I 2>&1 &
# stop
# find jekyll server process
ps -ef | grep jekyll
# substitute pid# with process id
kill -9 pid#

Using markdown syntax inside a HTML tag/block #

For a block, we use markdown="1",

<div markdown="1">paragraph</div>

For a tag, we use markdown="span",

<mark markdown="span">text</span>

Add search with lunrjs #

Download lunr.min.js and search.js and put them in root/js/. The newest version of lunrjs given here but I'm not sur if it works with this technique or not.

Create a file search.html in the root folder with content:

---
layout: page
title: Search on this page
---

<p class="p-intro">
<span id="search-process">{{re_loading}}</span> {{re_result}} <span id="search-query-container" style="display: none;">{{re_forkey}} "<strong id="search-query"></strong>"</span>
</p>
<ul id="search-results"></ul>

<script type="text/javascript">
window.data = {
{% for post in site.posts %}
{% if post.title %}
{% unless post.excluded_in_search %}
{% if added %},{% endif %}
{% assign added = false %}
"{{ post.url | slugify }}": {
"id": "{{ post.url | slugify }}",
"title": "{{ post.title | xml_escape }}",
"categories": "{{ post.categories | join: ", " | xml_escape }}",
"tags": "{{ post.tags | join: ", " | xml_escape }}",
"url": " {{ post.url | xml_escape }}",
"content": {{ post.content | strip_html | replace_regex: "[\s/\n]+"," " | strip | jsonify }}
}
{% assign added = true %}
{% endunless %}
{% endif %}
{% endfor %}
};
</script>
<script src="{{ site.baseurl }}/js/lunr.min.js"></script>
<script src="{{ site.baseurl }}/js/search.js"></script>

Note that, you can change some personal settings in the files search.js and search.html if you like.

Remark: if your site has so many posts, you can remove the last line ("content"....) to ignore the content from the search. You can even add "keywords" (resplace for "content") and put that "keywords" in the frontmatter, change also the term "content" in search.js by "keywords". That's what I did on this site.