[October 29, 2022]

Dear Past-self,

It’s 2022 now, and your commands don’t work anymore. You source code fails to compile with newer versions of the libraries. On top of that, several packages have not recieved updates in years. So, overall, it’s a dependency hell now. It’s high time that you moved to Hugo. In the meantime, there’s a dockerhub image which can be used for building and testing the site.

docker run -p 4000:4000 -v $(pwd):/site bretfisher/jekyll-serve

[July 3rd, 2019]

Dear Future-self,

In this post I will jot down how I created this site, becuase I know you will forget these. These are mostly notes taken from the tutorial series from this tutorial playlist by Mike Dane. Thanks Mike for the quick, to-the-point tutorial.

Jekyll Installation

This part is actually very simple and the official (upto date) instructions can be found on jekyll’s website. For ubuntu the commands are,

sudo apt-get install ruby-full build-essential zlib1g-dev
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install jekyll bundler

Setting up the project

To setup the barebones of the project simply run the following command,

jekyll new mywebsite

The project folder will be created at ./mywebsite. To start the server run,

cd mywebsite
bundle exec jekyll serve

Jekyll Features

  • Markdown Page
    • Front Matter
      • YAML key-values
      • Default Frontmatter
  • Drafts For drafts to appear on the rendered website, you need to run.
jekyll serve --draft
  • Posts
    • Permalink

Adding Default Frontmatter

Add following in config.yml file to set default front matter that should be added to pages.

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

Themes

There are a lots of themes available on rubygems website. Head over there and search for jekyll-theme. Pick any of the themes you like from there and head over to it’s Github page or homepage to check the preview. Then for installing that theme, say jekyll-theme-primer, run the following commands. For updating the theme, you also need to stop the jekyll serve command, if it is running.

Open Gemfile and add

gem "jekyll-theme-primer"

From terminal, run

bundle install

Open _config.yml and update the following line

theme: jekyll-theme-primer

Then restart the jekyll server using,

bundle exec jekyll serve

Layouts

Now layouts are the part of the site that controls the skeleton of different types of pages. These different types are controlled by different layouts. e.g. in the jekyll-minima theme we have 3 layouts, home, page, posts. You can define your own layouts by creating .html files in _layouts folder. Layouts usually have the base .html code that automatically gets inherited by posts or pages whenever the latter assigns a layout from its front matter. A sample layout can look like,

<!DOCTYPE html>
<html>
<head>
  <title>My Awesome Website!</title>
</head>
<body>
<h1>Draft Layout</h1>

{ { content }}

</body>
</html>

These layouts can also have front matters to inherit from other layouts that may contain a common structure to be used by multiple layouts. For example consider the following example.

<!-- _layouts/wrapper.html -->
<!DOCTYPE html>
<html>
<head>
  <title>My Awesome Website!</title>
</head>
<body>

Wrapper <br>
{ { content }}
<br> Wrapper

</body>
</html>

Now following are two example sublayouts that uses the wrapper layout.

<!-- _layouts/page.html -->
---
layout: wrapper
---
<h1>This is a page.</h1>

{ { content }}
<!-- _layouts/post.html -->
---
layout: wrapper
---
<h1>This is a Post.</h1>

{ { content }}

Variables

New variables can be defined in the front matter and accessed by layout.variable_name.

<!-- _layouts/post.html -->
---
layout: wrapper
author: bishal s.
---
<h1>This is a Post.</h1>
- by { { layout.author }}
{ { content }}

To access variable from an .md page using the wrapper use { { page.variable_name }}. Similarly, site level variables from \_config.yml can be accessed by { { site.variable_name }}. More info on different types of variables and an exclusive list of global variables visit jekyll/docs/variables