Customizing Jekyll

April 13, 2018 | 8 Minute Read

On my previous post, we looked at what Jekyll is and some its advantages. On this post, we will look at using the Long-Haul theme and see how we can customize it to change the templates as needed to include additional social media icons and also tweaking its css to change the styling of the site. We will also see how we can change the default image for the theme and add Disqus integration to allow visitors to comment on content.

Getting Started

We will start by cloning the Long-Haul Git Repository as follows:

    git clone https://github.com/brianmaierjr/long-haul

You can also Fork the repository and clone the forked version if you prefer. This will allow you to also make contributions of any changes to the original repository via Pull Requests.

The Long-Haul theme uses Gulp that manages the workflow of building the site using jekyll and serving it locally so you can preview and test the changes you make to the site. The Browsersync plugin watches the directory containing the files cloned and refreshes the browser window to show the latest changes.

If you haven’t installed Ruby, RubyGems, Bundler, or Jekyll and any of its pre-requisites as yet, please follow the steps on my previous post for details. You can use this functionality to edit markdown files and see the changes show up on your browser automatically after you save.

Once you’ve installed all the tools needed to use Jekyll as described on my previous post, you can run the following steps to serve the default content from the Long-Haul theme:

Install all Ruby Gems required by the Long-Hault theme:
```
$ bundle install
```
Install all Gulp dependencies:
```
$ npm install
```
Start Jekyll and watch for file changes by running Gulp:
```
$ gulp
```

You should now be able to navigate to http://localhost:3000 and see the main page that looks similar to the following figure:

Site Layout

So now that we have the Long-Haul theme setup, we can dig right into making our customizations. In this section, we will look at some of the most important files and directories of the site we cloned above. These files will be the focus of customization on the next section.

File/Directory	Description
`*.md`	Markdown files that will be rendered to .html files.
`_config.yml`	Jekyll configuration file
`_includes`	Contains partials with liquid templating directives used by the templates in the _layouts directory
`_layouts`	Contains templates for the type of content that can be generated. The types of content are defined using YAML. There can be templates defined for posts and pages among others based on the theme. You can also define custom content types.
`_posts`	Contains posts written in markdown format.
`_site`	All markdown files and assets processed by Jekyll are rendered into html files and placed in this directory.

Configuration File (_config.yml)

The _config.yml file is the main configuration file that defines site-specific items including the title and description of the site. Detailed configuration directives for this file are documented in the Jekyll Configuration section. An example _config.yml file is shown below:

title: Simplicity
description: Another Jekyll Blog

url: https://jekyllrb.com/
baseurl: ""
paginate_path: "blog/page:num/"
permalink: blog/:title/

markdown: kramdown
highlighter: rouge
gems: [jekyll-paginate]
paginate: 5

navigation:
 - title: Home
   url: /index.html
 - title: About
   url: /about
 - title: Contact
   url: /contact

social:
   github: jekyll
   twitter: jekyll
   facebook: jekyll
   email: abc@abc.com

google_analytics: "UA-58263416-1"

In the above _config.yml file, the title key becomes an html <title> tag. The description key isn’t used by this theme, but can be used similarly in a description meta tag for instance.

Some entries like the navigation list for instance identify the navigation links for the site. The title specifies the text while the url specifies the path to the resource. You will see about.md and contact.md files in the root directory for the theme. Jekyll renders these files into index.html files in the _site/about and _site/contact directories. When the jekyll server is running, the pages can be accessed with http://localhost:4000/about/ and http://localhost:4000/contact/ respectively.

The gems key in the configuration file above tells Jekyll to use the pagination plugin and specifies that the index page is to have upto 5 posts on each page. The paginate_path and permalink keys specify how the index pages and page directory structure is to be setup. This directory structure determines the URLs used to access each of the posts. With the configuration above, the 2nd set of 5 blog posts is accessed by specifiying http://localhost:4000/blog/page2 in the URL, while a particular post can be accessed by specifying http://localhost:4000/blog/post-title in the URL.

Finally, the social list specifies the social networking site pages to visit when the corresponding icons are clicked.

Templates & Partials

The _layouts directory in the directory structure contains templates for the types of pages that can be created. These pages are written in the liquid templating language. These templates consist of a combination of html and liquid tags that define the structure of the content. The default.html file within this directory is listed below:

<!DOCTYPE html>
<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->
<!--[if IE 7]><html class="no-js lt-ie9 lt-ie8" <![endif]-->
<!--[if IE 8]><html class="no-js lt-ie9" <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->

{% include head.html %}

<body>

   {% include header.html %}

   <div class="content">
      <div class="container">
         {{ content }}
      </div>
   </div><!-- end .content -->

   {% include footer.html %}
   {% include scripts.html %}

</body>

</html>

The above template defines the structure for pages including the About and Contact pages in the site. The template includes partials (html/liquid fragments) from the _includes directory. In the above example the head.html file consists of content that will go into the <head> section of the template. This content includes various meta tags, the title tags and links to stylesheets and JavaScript used on the pages.

The _includes directory as we’ve seen consists of the fragments that can be included when building templates.

You’ll also see assets and css directories that contain images, javascript and style sheets used in the different templates. The Long-Haul theme uses the Sass CSS extension language to manage the styling of the site. You will find an assets/scss directory with stylesheets organized in modules. The _config.scss file contained all the color definitions for the site. The color for the hyperlinks for instance can be changed by editing the primary-color for instance. Sass will compile these scss files to css. These resources can then be included by the templates and partials in the _includes and _layouts directories. They can also be referenced by the posts using the markdown image_with_caption tags for instance.

The about.md, contact.md, used in the site navigation, and articles.md in the root directory of the theme. The articles.md and index.html files are a litle more interesting. The articles.md file accessible as http://localhost:4000/articles/ provides a the full list of posts as articles. There are next and previous controls on the article pages to browse through the available articles. The index.html file uses the Jekyll paginate plugin to present the five most recent posts. As mentioned before, the number of posts displayed is determined by the paginate: key in _config.yml.

Comments using Disqus

Disqus is a comments hosting platform that can be used to interact with users on a Jekyll site. You can register for the basic plan that is free and supported via adds. Once an account is created, you will receive an html snippet that can be added to the footer of the post.html to display a comment box and list of comments.

Concluding Notes

The above only scratches the surface of how convenient a static site generator can be for building blogs and some web sites quickly using markdown syntax. If you are interested in exploring more on your own, Jekyll Themes is an excellent source to get you started. The Jekyll Documentation a good reference to get started with customization or developing your own themes.

« Jekyll for Blogging

Riding Change