Jekyll, A Simple Way To A Static Website

Jekyll Jackal [source]

Apart from the occasional ‘GitHub-er’ or fanboy, I feel that not many people talk about Jekyll anymore, possibly for good reason.

Assuming you don’t want to use a no-code website builder or a template on WordPress, it can be useful for setting up a custom static website quickly.

If you need a more complex application, especially one that is not static, Jekyll is not the best option. That said, you will need some knowledge of HTML, CSS, a touch of Ruby, and possibly JavaScript depending on what you are trying to achieve.

If you are still reading, here is a quick surface-level overview of Jekyll, The Good, The Bad, And the Ruby.

Getting Started

To get started, install Ruby, bundler, and Jekyll itself.

The Ruby dev environment can be installed on Windows or Linux. Granted I have had odd experiences with Windows in the past. So if you can, maybe lean towards Linux.

Linux Install

sudo apt install ruby-full
sudo apt install jekyll

Windows Install

For Windows, I highly recommend using the Jekyll on Windows Instructions. But here are the general steps anyway. Keep in mind you can install Windows Subsystem for Linux (WSL) so that installing Jekyll is not as annoying, but if you don’t like Linux or want to deal with it then don’t.

Run the Ruby Installer

Then install Jekyll using gem

gem install jekyll bundler

Create A Project

Note that you may need to run these commands as an admin or root.

bundle exec jekyll new project-name

mkdir project-name
cd project-name
bundle exec jekyll new .

The general layout of a Jekyll website looks like this. The bundle command should automatically generate most of it.

_includes/
_layouts/
_posts/
assets/
_config.yml
index.md

Initial Preparation

Once the project is generated, it’s a good idea to take a look at the Gemfile. The Gemfile is where resources and dependencies needed for the project are defined. Usually Jekyll will try to be “helpful” and add stuff we don’t need for a base project.

Open up the Gemfile and remove anything related to a theme if you don’t want it like ‘minima’ etc. If you know what you are doing, then remove anything else you don’t want.

Then read the comments, they can be rather helpful.

source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# 	bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
gem "jekyll", "~> 4.3.1"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.12"
end

# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
gem "tzinfo", ">= 1", "< 3"
gem "tzinfo-data"
end

# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]

# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
# do not have a Java counterpart.
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

Running The App

In the root of the project, add your page md files for your pages. The index.md or index.markdown will typically be the home page.

Then start the application. Change directories into the root of your new project then run the following command.

bundle exec jekyll serve

Or depending on how you installed Jekyll, you may be able to just run:

Jekyll serve

Now you should be able to reach these pages from the browser. The default port is usually 4000. Make sure to add something to the index.mardown or index.md file or the page will probably be blank by default.

http://localhost:4000/

If you get an error like this:

“… check_for_activated_spec!’: You have already activated public_suffix 6.0.1, but your Gemfile requires public_suffix 4.0.6. …”

Or it’s complaining about not finding a specific dependency Then try to clean out the bundle.

bundle clean --force

Then run the bundle exec command again.

Includes and Layouts

Two important features that make Jekyll useful, and also a menace if abused are the _includes and _layouts directories.

You can think of “layouts” as extendable/reusable page structures and “includes” as chunks or blocks of reusable code or html.

Each markdown page can optionally extend a layout in the _layouts directory. Then typically you can ‘include’ a block of HTML in a layout or markdown file. This allows for some code reuse and segmentation of purpose.

Here is a simplified example with a home page and a loop for displaying each post with a link. This example does not use themes or templates, that way it’s easier to play around with and understand before you add themes and plugins which may do the work for you.

You can check out the full project on Github.

_layouts/base.html

The base will be the general framework for every page in this example.

<!DOCTYPE html>
<html>

{% include head.html %}

<body>
  <main>
    <div class="main-content-wrapper">
      {{ content }}
    </div>
  </main>
</body>

</html>

_layouts/home.html

Then the home layout extends the base.html layout.

---
layout: base
---
{{ content }}

{% for post in site.posts %}

  {% include card.html %}

{% endfor %}

_layouts/post.html

Then the post layout also extends the base.html layout.

---
layout: base
---
<h1>{{ page.title }}</h1>

{{ content }}

Plugins

Another great feature of Jekyll is plugins. As you can probably guess, they allow for some ready-to-use out-of-the-box functionality ranging from automated SEO to page structure.

For example, the jekyll-seo-tag plugin will dynamically populate most if not all needed meta tags for basic SEO needs and social cards. I won’t bore you with the details when others have already written detailed docs on the subject: Link To SEO Tag Plugin Github

Why

Manipulating pages with Ruby is cool, but why would you use Jekyll over any other tool? It comes down to preference, but my argument is simplicity if all you need is a simple and customizable static website.

If you try to make your app ‘fancy’, Jekyll’s charm can become its biggest flaw. I’m not saying it’s impossible, people have done it, but the structure can become confusing, and adding complex features like a database doesn’t make much sense.