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.

Pros

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

Cons

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

Installation

Both Ruby and Gem need to be installed.

gem install jekyll bundler

Verify

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

Content

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

URL

http://localhost:4000/jekyll/update/2017/09/24/welcome-to-jekyll!.html

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

_posts/2017-09-24-my-first-blog-post.md

Layout

layout: "post"

Overwrite

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

Drafts

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

my-draft-blog-post.md

Then run following command

jekyll serve --draft

Pages

Create page in root folder, such as donate.md, and set layout as page

layout: "page"

Then the URL will be

http://localhost:4000/donate

Premalinks

permalink: "/my-new-url/"

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

Default Front Matter

Defined in _config.yml file

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "post"
      title: "My Title"

Then restart jekyll server.

Theme

Default theme is minima, other themes can be downloaded from https://rubygems.org, 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.

Layouts

Create <layout_name>.html in _layouts folder

<h1>This is page</h1>
<hr>

{{ 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>
<hr>

{{ content }}

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

<html>
<head>
  <meta charset="UTF-8">
  <title>Doument</title>
</head>
<body>
  Wrapper <br>
  {{ content }}
  <br> Wrapper
</body>
</html>

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

Variables

Front Matter variables

{{ layer.author}}
{{ page.title }}
{{ page.author }}
{{ site.title }}

The site values are from _config.yml file

Other variables can be found in https://jekyllrb.com/docs/variables/.

Includes

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

<html>
<head>
  <meta charset="UTF-8">
  <title>Doument</title>
</head>
<body>
  {% include header.html %}
  {{ content }}
</body>
</html>

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 %}

Conditionals

{% 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

{{ site.data.people }}

{% for person in site.data.people %}
  {{ person.name }}, {{ 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

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

Then restart jekyll server

Update home.html file

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

Hosting on Github Pages

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