Category: jekyll

Learning – Jekyll

Learning - Jekyll

Developers describe Jekyll as "Blog-aware, static site generator in Ruby". It is classified as "Static Site Generators" and "Self-Hosted Blogging / CMS", similar to WordPress for blogging.


  • Simple - No more databases, file based.
  • Static - Markdown (or Textile), Liquid templating language, HTML & CSS, etc.
  • Blog-aware - Includes permalinks, categories, pages, posts, and custom layouts.
  • Theme - Can be downloaded from rubygem
  • Github - Integration allow publish to Github


  • No search, but it is SEO friendly
  • No plugin
  • No image resizing
  • No tag


Both Ruby and Gem need to be installed.

gem install jekyll bundler


jekyll -v

Create a Site

jekyll new ga_blog

Then there is ga_blog folder created.

Launch the Site

For the first time, run

bundle exec jekyll serve

Subsquence time

jekyll serve

Then the website can be accessed from http://localhost:4000/

Folder structure

The _posts folder hosts posts.

The _site folder hosts the finial product of website.

Front Matter


layout: post
title: "Welcome To Jekyll!"
date: 2017-09-24 15:58:59 -0700
categories: jekyll update



Also can create custom attribute in Front Matter.

Writing Posts

The posts can be in subfolders too, the URL will add subfolder in the path.

Filename format



layout: "post"


title: "This is the new title"
date: 2017-09-20 15:58:59 -0700


Create folder called _drafts, and save draft posts in this folder with name only, the date will be the today's date.

Then run following command

jekyll serve --draft


Create page in root folder, such as, and set layout as page

layout: "page"

Then the URL will be



permalink: "/my-new-url/"


permalink: /:categories/:year/:month/:day/:title.html

Default Front Matter

Defined in _config.yml file

      path: ""
      type: "posts"
      layout: "post"
      title: "My Title"

Then restart jekyll server.


Default theme is minima, other themes can be downloaded from, and search jekyll-theme.

Update Gemfile

gem: "jekyll-theme-hacker"

Then stop Jekyll server and run command

bundle install

Update _config.yml file

theme: jekyll-theme-hacker

Then start jekyll server using following command

bundle exec jekyll serve

If there is no output on the page, normally, it is because no layout defined in theme.


Create <layout_name>.html in _layouts folder

<h1>This is page</h1>

{{ content }}

Define sub layout, then can be used in other layout.

For example, in post.html layout

layout: wrapper

<h1>This is a post</h1>

{{ content }}

Then it will use wrapper layout defined in wrapper.htm below

  <meta charset="UTF-8">
  Wrapper <br>
  {{ content }}
  <br> Wrapper

Use this method for other layouts, then can have html skeleton.


Front Matter variables

{{ page.title }}
{{ }}
{{ site.title }}

The site values are from _config.yml file

Other variables can be found in


Create a folder called _includes

Create a file called header.html in _includes folder as below

<h1>{{ site.title }}</h1>

Then update wrapper.html file

  <meta charset="UTF-8">
  {% include header.html %}
  {{ content }}

Then every page using wrapper.html will use header.html to display header.

To define variable during include as below

{% include header.html color="blue" %}

Then access in header.html file as below

<h1 style="color: {{ include.color }}">{{ site.title }}</h1>

Looping Through Posts

Update _layouts/home.html

{% for post in site.posts %}
  <li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}


{% if page.title == ... %}
{% elsif page.title == ... %}
{% else %}
{% endif %}

For example

{% for post in site.posts %}
  <li><a style="{% if page.url == post.url %}color:red;{% endif %}" href="{{ post.url }}">{{ post.title }}</a></li>

Data file

Create a folder called _data, put YAML, JSON or CSV files in it.

For example, people.yml file

- name: "Mike"
  occupation: "Giraffe Academy"

- name: "Steve"
  occupation: "Firefighter"


In home.html file

{{ }}


{% for person in %}
  {{ }}, {{ person.occupation }} <br>
{% endfor %}

Static Files

Those files have no Front Matter, can be stored in any folder. For example, in assets folder, in home.html file,

{% for file in site.static_files %}
  {{ file.path }} <br>
{% endfor %}

Configure Front Matter in _config.yml file

  - scope:
      path: "assets/img"
      image: true

Then restart jekyll server

Update home.html file

{% for file in site.static_files %}
  {% if file.image %}
    <img src="{{ file.path }}" alt="{{ }}">
  {% endif %}
{% endfor %}

Hosting on Github Pages

Create repository called ga_blog, and don't init with README.

Update _config.yml file

baseurl: "ga_blog"


git init
git checkout -b gh-pages
git add .
git commit -m "initial commit"

Add remote repo

git remote add origin<name>/ga_blog.git


git push origin gh-pages

Then go to setting in Github page, find out published URL