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/"
or
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 }}
or
{% 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.
Update _config.yml file
baseurl: "ga_blog"
Then
git init
git checkout -b gh-pages
git add .
git commit -m "initial commit"
Add remote repo
git remote add origin https://github.com/<name>/ga_blog.git
Push
git push origin gh-pages
Then go to setting in Github page, find out published URL
References
Tutorials