Jekyll

Posted on:September 23, 2022 at 03:22 PM

Basics

List of jekyll plugins supported on GitHub-Pages

List-of-supported-languages-and-lexers in Jekyll

Markdown Cheatsheet

Sites for pics

Useful Jekyll commands

Getting started

$ sudo apt-get install ruby-full
# Install Ruby Gems to ~/gems
export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"
$ gem install gem_name
$ bundle show gem_name
$ bundle install
$ jekyll new myblog
      $ bundle exec jekyll serve
/assets
/_layouts
/_includes
/_sass

Jekyll Github Workflow (Using Jekyll with Bundler)

$ sudo apt-get install ruby-full

Then set GEM_HOME and PATH in ~/.bashrc.

export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"
$ gem install bundler
$ git init JEKYLL-SITE-REPOSITORY-NAME
# Ignore metadata generated by Jekyll
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata

# Ignore folders generated by Bundler
.bundle/
vendor/
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
$ bundle install --path vendor/bundle
$ git add .
$ git commit -m "Initial commit"
$ git remote add origin github.com-saurabhp75:saurabhp75/karmbhumi.git
$ git push -u origin master
$ bundle exec jekyll serve
$ git push -u origin master

Working on draft blog posts

All your unpublished blog posts reside under ./_drafts folder. This allows you to work on blog posts without publishing them to the live site. If you want the build to include all of our draft blog posts you could run jekyll like this:

jekyll build --drafts

Liquid

Liquid is a templating language which has three main parts: objects, tags and filters

Objects

Objects tell Liquid where to output content and are denoted by double curly braces. {{ page.title }}

Tags

Tags create logic & control flow for templates, and are denoted by curly braces and percent signs. for eg.
{% if page.show_sidebar %} {% endif %}

Filters

Filters change the output of a Liquid object. {{ "hi" | capitalize }}

Front Matter

Snippet of YAML which sits between two triple-dashed lines at the top of a file and is used to set variables for the page. Front matter variables are available in Liquid under the page variable eg. {{ page.my_number }}

\---
my_number: 5
\---

Layouts

Layouts are templates(html files) that wrap around your content. They live in a directory called _layouts. To use a layout, set a layout variable in front matter. eg.

\---
layout: default
title: Home
\---

<h1>{{ "Hello World!" \| downcase }}<h1>

Includes

The include tag allows you to include content from another file stored in an _includes folder. Usage of include tag in an html file, where navigation.html is a file under _includes folder. eg.
{% include navigation.html %}

Data Files

Jekyll supports loading data from YAML, JSON, and CSV files located in a _data directory. Data files are a great way to separate content from source code to make the site easier to maintain. for eg. you can store contents of navigation.

for eg. _data/navigation.yml Jekyll makes this data file available to you at site.data.navigation

Assets(CSS, JS, images etc)

Place them in your site folder and they’ll copy across to the built site. Jekyll sites often use this structure to keep assets organized.

├── assets
 |   ├── css
 |   ├── images
 |   └── js

Sass

Sass is a fantastic extension to CSS baked right into Jekyll. /assets/css/styles.scss.

\---
\---
@import "main";

The @import “main” tells Sass to look for a file called main.scss in the sass directory (_sass/ by default which is directly under root folder of your website). /_sass/main.scss

.current {
  color: green;
}

to access css file from html page.
<link rel=“stylesheet” href=“/assets/css/styles.css”>

Blogging

In Jekyll, blogging is powered by text files only instead of a db.

Posts

Blog posts live in a folder called _posts. The filename for posts have a special format, the publish date, then a title, followed by an extension. Jekyll makes posts available at site.posts. eg _posts/2018-08-20-bananas.md.

\---
layout: post
author: jill
\---

A banana is an edible fruit – botanically a berry – produced by several kinds of large herbaceous flowering plants in the genus Musa.

In some countries, bananas used for cooking may be called “plantains”, distinguishing them from dessert bananas. The fruit is variable in size, color, and firmness, but is usually elongated and curved, with soft flesh rich in starch covered with a rind, which may be green, yellow, red, purple, or brown when ripe.

_layouts/post.html

\---
layout: default
\---

<h1>{{ page.title }}</h1>
<p>{{ page.date | date_to_string }} - {{ page.author }}</p>

{{ content }}

This is an example of layout inheritance. The post layout outputs the title, date, author and content body which is wrapped by the default layout.

List posts

\---
layout: default
title: Blog
\---

\<h1>Latest Posts</h1>

<ul>

  &nbsp;&nbsp;&lt;li>
    &nbsp;&nbsp;&nbsp;&nbsp;&lt;h2>&lt;a href post.url  post.title a></h2>
    &nbsp;&nbsp;&nbsp;&nbsp;&lt;p>```{{ post.excerpt }}```</p>
  &nbsp;&nbsp;&lt;/li>
 endfor %}

</ul>

Built-in variables in Jekyll

Collections

Collections are similar to posts except the content doesn’t have to be grouped by date. To set up a collection you need define them in Jekyll configuration file, _config.yml(by default). eg.

collections:
  authors:

Define authors in files under _authors folder eg. _authors/ted.md, _authors/jill.md etc. Note: You need to restart Jekyll server whenever, config file changes.

Output a page

By default, collections do not output a page for documents. In case you want each author to have their own page, tweak the collection configuration in _config.yml. Also, you’ll need to create a layout for authors in _layouts/author.html.

collections:
  authors:
    output: true

link to output page: author.url

Front matter defaults

List author’s posts

Link to authors page

Deployment

Gemfile

It’s good practice to have a Gemfile for your site. This ensures the version of Jekyll and other gems remains consistent across different environments.

Plugins

To use the plugins, you need to add them to your Gemfile. If you put them in a jekyll_plugins group they’ll automatically be required into Jekyll.

source 'https://rubygems.org'

gem 'jekyll'

group :jekyll_plugins do
  gem 'jekyll-sitemap'
  gem 'jekyll-feed'
  gem 'jekyll-seo-tag'
end

Then add these lines to your _config.yml. Then install them by running a bundle update. plugins:

Environments

Sometimes you might want to output something in production but not in development. Analytics scripts are the most common example of this. You can set the environment by using the JEKYLL_ENV environment variable when running a command. For eg:

$ JEKYLL_ENV=production bundle exec jekyll build

By default JEKYLL_ENV is development. The JEKYLL_ENV is available to you in liquid using jekyll.environment. So to only output the analytics script on production you would do the following.

  <script src="my-analytics-script.js"></script>
{% endif %}

Deployment

The final step is to get the site onto a production server. The most basic way to do this is to run a production build and copy the contents of _site to your server. A better way is to automate this process using a CI or 3rd party.

$ JEKYLL_ENV=production bundle exec jekyll build