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 bundlerVerify
jekyll -vCreate a Site
jekyll new ga_blogThen there is ga_blog folder created.
Launch the Site
For the first time, run
bundle exec jekyll serveSubsquence time
jekyll serveThen 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!.htmlAlso 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.mdLayout
layout: "post"Overwrite
title: "This is the new title"
date: 2017-09-20 15:58:59 -0700Drafts
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.mdThen run following command
jekyll serve --draftPages
Create page in root folder, such as donate.md, and set layout as page
layout: "page"Then the URL will be
http://localhost:4000/donatePremalinks
permalink: "/my-new-url/"or
permalink: /:categories/:year/:month/:day/:title.htmlDefault 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 installUpdate _config.yml file
theme: jekyll-theme-hackerThen start jekyll server using following command
bundle exec jekyll serveIf 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: trueThen 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.gitPush
git push origin gh-pagesThen go to setting in Github page, find out published URL