With Jekyll you can create a blog without using PHP, Node.js or any server-side platform, just with static pages you can upload to an object storage service like AWS S3.

Table of Contents

Install

Instructions for Ubuntu:

  1. Install Ruby and other required dependencies. 
    sudo apt-get install ruby-full build-essential zlib1g-dev
  2. Ruby packages are called gems. Set up a gem installation directory for your user account. 
    echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  3. Install Jekyll and Bundler gems. 
    gem install jekyll bundler

Note: if, after a system update, Jekyll stops working, try to reinstall it by running the previous command.

New project

  1. Create a new project. 
    jekyll new <project-name>
  2. This will create a new directory with the project name. cd to this directory. 
    cd <project-name>

Local server

  1. You can view your site locally by creating a local server. 
    bundle exec jekyll serve
    • Go to http://localhost:4000 to view your new site.
    • If it shows an error, try adding webrick to your dependencies: 
      bundle add webrick
    • If you want to access your local server from other devices inside your LAN, add --host=0.0.0.0 to the end of the serve command.

Build your site

bundle exec jekyll build

Project structure

├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
└── _posts
    └── 2021-09-24-welcome-to-jekyll.markdown
  • You can create your posts or pages with Markdown or HTML. Post are usually written in Markdown.
  • Posts need to be created inside _posts folder following this name syntax: 
    year-month-day-post-title.md
  • When you build your site, a new folder called _site will contain all of your site generated pages and assets, so you can copy and paste them in your server or hosting service.

Front matter

All post pages must begin with a content called “front matter”. This “front matter” must begin and end with three dashes (---). This is needed for setting post metadata and template (layout). You can add any variable to the “front matter”.

---
layout: post
title: My post
description: "Some description"
date: 2021-01-01 12:00:00 +0200
---

Themes

Using own CSS files

By default, your site will use a theme called “minima”. But you can remove it and use your own CSS styles. Simply remove theme: minima from _config.yml and gem: "minima", "~>2.5" from Gemfile. Then run bundle install to update the configuration.

If you are using your own theme, you will need to create a folder called _layouts in the main folder where you will create your templates. An example of a template file is this one:

# ./_layouts/post.html

<article>
  <h1 class="post-header">{{ page.title | escape }}</h1>
  <div class="post-content">{{ content }}</div>
</article>
  • You need to use {{ }} to refer to a jekyll variable (Jekyll uses Liquid template language). You will find more info about variables below.

You refer to these layout files by using the layout parameter inside your page or post “front matter”, or even inside another layout.

# ./_layouts/default.html
<!DOCTYPE html>
<head>
...
</head>
<body>
  <main>{{ content }}</main>
...

# ./_layouts/post.html
---
layout: default
---
<article>
  <h1>{{ page.title | escape }}
  <div>{{ content }}</div>
</article>

You can also create a folder called _includes where you can add parts of your site that can be reused many times, such as the header (the top bar of the site, which usually includes the site title and a navigation menu), the footer, etc.

You can refer to these “include” files by adding this to your page, post or layout (where you want them to appear):

{% include filename.html %}

Installing themes via gems

Gem-based themes are easy to install, just add gem "<theme gem name>" to your project’s Gemfile, run bundle, set the theme in your _config.yml file (theme: <theme-name>) and, finally, run bundle update.

Adding images or other assets to your site

Create a folder called assets in the main directory. In this folder you will add files like images, css, javascript, etc.

You can add an image to your markdown post by referring its location:

![Image description](/assets/imgs/image.jpg)

For referring other files like PDFs:

[link text](/assets/files/test.pdf)

For adding a CSS file:

# ./_includes/head.html
<head>
  <link rel="stylesheet" href="{{ "/assets/css/main.css" | relative_url }}">

Variables

Jekyll uses the Liquid template language. To refer to an existing variable, you need to write {{ variable_name }}. For example:

{{ page.title }}

This is a list of Jekyll variables (you can find all variables at Jekyll website):

  • page: This variable contains metadata about the page or post (the info inside the page “front matter”).
    • page.title
    • page.excerpt: Contains the first paragraph of a page.
  • site: This variable contains information about the site. These are some of the variables:
    • site.pages: a list of all pages.
    • site.posts: a reverse chronological list of all posts. Every post is a variable similar to page.

Plugins

You can add plugins by adding their name in the appropriate section inside Gemfile:

# ./Gemfile
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "jekyll-paginate"
  gem "jekyll-sitemap"
end

Then, run the command bundle install to install the plugin.

If you have any suggestion, feel free to contact me via social media or email.