Home Jekyll
Post
Cancel

Jekyll

Jagdish Dev on Sep 12021-09-01T00:00:00+05:30
8 min read

Jekyll

Jekyll is a static site genrator. It converts markdown files into static website. Used as alternative of wordpress or cms.

Jekyll is better than any cms like wordpress. because it generates static sites from markdown and reduce the complexity of mantaining server/database/security with less resources usage.

Github pages also uses jekyll

official docs here and Tutorial Video’s here

Installation for Ubuntu

Installing Dependencies and ruby

1

sudo apt install ruby-full build-essential zlib1g-dev   # Dependencies

Adding Environment Variables in ~/.bashrc file to configure ruby

1
2
3
4

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Installing Jekyll and Bundler

1

gem install jekyll bundler

Setup

Creating project and starting server

1
2
3
4
5
6
7
8

jekyll new my-project-name  # Creating a new jekyll project

cd my-project-name

bundle exec jekyll serve	# Build site and Start jekyll server for first time
jekyll serve	# builds site and start jekyll server

jekyll build	# Bulid site

Directory structure

1
2
3
4
5
6
7
8

.
├── _posts		# Stores all posts markdown files
└── _site		# Final static version of site
└── _config.yml	  # Configration of your data
├── about.markdown	# Default about us page
├── index.markdown	# Default home page
├── Gemfile		# gem packages details file

Liquid

It is a templating language which has three main components

  • objects - output variables template, use {{ and }} for example {{ page.title }}

  • tags - logic control template, use {% and %} for example

    1
2
3

    {% if page.show_sidebar %}
<div class="sidebar">sidebar content</div>
{% endif %}

  • filters - it changes the output of liquid object. use |. For example: {{ "h1" | capitalize }}

Escaping Liquid from file

If your post or any file include liquid syntax then jekyll may display / return error and to resolve that we can use {% word %} with value asraw to start ignoring and endraw to stop ignoring.

1
2

{% #raw %}	# Remove `#` from raw
{% #endraw %}	# Remove `#` from endraw

we are using jekyll liquid raw and endraw to escape liquid error / rendering from this file, thats why we used # before endraw

Front Matter

It is the information about our blog post. It can be written in yaml, or json.

it is used in the head of file for example

1
2
3
4

---
my_number: 5
---
{ { my_number } }

Writing Posts

_posts folder includes all the posts.

naming convention - year-month-date-blog-name.markdown

To create new post just create file with naming convention inside _posts/ or _posts/dir/.

For Example:

1
2
3
4
5

# Inside _posts/some_dir/
---
layout: post
---
Some Other Post

Draft Posts

Create _drafts folder to store draft posts

create them like new post and can skip date in name only till it is draft

1
2

# To render draft in server
jekyll serve --draft

Creating Pages

Creating page is simple, just create page-name.md file or folder/page-name.md file inside folder and use layout: page

permalink is optional by default it will use file path from root folder.

default permalink of post is /:categories/:year/:month/:day/:title and we can change it by adding permalink: "/path/" in front matter of post / post

Default Front Matter

We can set default front matter in _config.yml file.

1
2
3
4
5
6
7

# Syntax of defining default value

defaults:
  - scope:
      path:
    values:
      # values

For example setting default value for all posts

1
2
3
4
5
6
7
8
9

# Inside _config.yml

defaults:
  - scope:
      path:
      type: posts
    values:
      layout: post
      parmalink: "/:categories/:title/"

Make sure to re-run jekyll server after editing config.yml file

1

jekyll serve

Themes

By default jekyll uses minima theme.

We can search for themes jekyllthemes.io or github repos or rubygem

For demo i will use jekyll-theme-chirpy

To install any theme please check official docs of theme first

Basic steps:

  1. Add theme name in GemFile. for example: gem "jekyll-theme-chirpy"
  2. Install theme by command bundle install in terminal
  3. Update theme in _config.yml file. for example: theme: jekyll-theme-chirpy
  4. Update layout as per theme

Layouts

We can Create layouts in _layouts folder in root directory folder and create a new file default.html or post.html or anyname.html

by default html file inside _layouts can attributes like page.title or content or any attribute of page

1
2
3
4
5
6
7
8
9
10
11

<!-- Inside _layouts/anyname.html -->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

Now we can call layout from any file in front matter just by calling layout: layout-file-name-without-html

Variables

Variables are used to retrive or store data. Official Doc here

We can create variables in front matter and call them as Liquid

Global Variables:

  • content - Returns Content of post or page
  • layout.param - returns param value from layout front matter
  • page.param - returns param value from post / post front matter

  • site.param - returns param value from _config.yml file

  • paginator (check docs) - only if paginate configruration option is set, then accessable and for details check docs

For Example created a post layout:

1
2
3
4
5
6
7
8
9
10
11

---
author: "JD"
---

<h1>This is a post</h1>
<hr />

<p>author: {{ layout.author }}</p>
<p>title: {{ page.title }}</p>

{{ content }}

Includes

Includes is used to import other layouts.

To use include we need to create _includes folder in root directory and inside that we have to create file.html and it can do all function as layout.html file like front matter, calling variable with liquid

To call file, syntax used is {% include file.html param1=value1 param2=value2 %}

for example created _includes/demo-header.html and calling demo-header from post layout:

1
2
3
4

<!-- demo-header.html file -->
<h1 style="color: {{ include.color }};">Site Title: {{ site.title }}</h1>
<hr />
<br />

1
2
3
4
5
6
7
8

<h1>{% include demo-header.html color="blue"%}</h1>

<h1>This is a post</h1>
<hr />

<p>title: {{ page.title }}</p>

{{ content }}

Looping Through Posts

We can loop thorough any array by call {% for item in items %} and ending it with {% endfor %}

for example looping through posts and pages in home layout file:

Inside _layouts/home.html

1
2
3
4
5
6
7
8
9

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

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

Conditions

if condition can be called with {% if condition %}, elseif condition with {% elsif condition %}, else with {% else %} and end with {% endif %}

for example calling page if page.title exist or page.title == "demo" inside _layouts/home.html

1
2
3
4
5
6
7
8
9
10
11
12
13

{% for post in site.pages %}

  {% if post.title %}
    <a href="{{ post.url }}">{{ post.title }}</a>
    <br>

  {% elsif post.title == "demo" %}
    <a href="{{ post.url }}">{{ post.title }}</a>
    <br>

  {% endif %}

{% endfor %}

Data Files

Data files are used to retreive data. they support yaml, json file.

Inside _data folder we create data files.

For example created _data/people.json file to get all people details and call them in home page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[
  {
    "id": 1,
    "name": "name1"
  },
  {
    "id": 2,
    "name": "name2"
  },
  {
    "id": 3,
    "name": "name3"
  }
]

Calling data in home page layout

1
2
3
4
5

<p>All people: {{ site.data.people }}</p>

{% for people in site.data.people %}
<p>People {{ people.id }}: {{ people.name }}</p>
{% endfor %}

Static Files

All files other then json and yml file will be taken as static files

It is a good pratice to store static files in folder like assets or with any name and inside that we can create sub directories like images, pdfs , etc. to organize them.

We can also give front matter to static files from _config.yml file. for example : giving image: true property for files inside assets/images.

we can loop to call static files for site.static_files and they have property like path, basename, extname, etc

1
2
3

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

Hosting on Github Pages

Pre-requisites:

  • Github Account
  • Git Installed on Device
  • Jekyll Installed on Device

Steps to host jekyll site on Github pages:

  1. Create New Repository

  2. Create Jekyll Project

  3. Update baseurl in _config.yml file to your github repository name

    1
2

    <!-- Inside _config.yml -->
baseurl: "repository-name"

  4. Add git to local file to update (Skip if already initialized)

    1

    git init

  5. Creating gh-pages branch (by default github pages uses gh-pages branch)

    1

    git checkout -b gh-pages

  6. Make commit (Skip if already commited)

    1
2

    git add .
git commit -m "initial commit"

  7. Add Github remote url

    1

    git remote add origin <github-repo-url>

  8. Pushing Changes to github

    1

    git push origin gh-pages

  9. Enabling Github Pages

    • Go to repository setting and enable github pages (if not already enabled)
    • Visit the url of your site
jekyll, notes
jekyll notes
This post is licensed under CC BY 4.0 by the author.
Recent Update
Contents

Node Mysql Postgresql

-