Post

The Ultimate Jekyll Blogging Guide

A Guide on how to setup a static blogging or portfolio site using jekyll.

Posted
By Nahil Rasheed
4 min read

The Core Components

Jekyll

Jekyll is a static site generator that transforms plain text into static websites and blogs. It’s written in ruby and is fast, easy, and open source.

Chirpy

Chirpy is a minimal, responsive, and feature-rich Jekyll theme for technical writing. It has built-in support for light/dark mode, search, SEO and so much more!.

Github pages

GitHub Pages is a free web hosting service provided by GitHub. It allows users to host static websites directly from their GitHub repositories.

Setup Jekyll

Install ruby and other prerequisites.

1
2

sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev git

To avoid installing RubyGems packages as the root user:

1
2
3
4

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Install Jekyll and Bundler

1

gem install jekyll bundler

Confirm installation by using jekyll -v

Checkout jekyll installation docs here.

Use Chirpy

To create a site using the Chirpy Starter.

  • Sign in to github and go to the Chirpy Starter page.
  • Click the button Use this template -> Create a new repository, and name the new repository USERNAME.github.io
  • Clone the repo to your local machine using git clone repo-url.
  • Install dependencies
    1
2

      cd repo-name
  bundle

Checkout Chirpy docs here.

Build site

To preview the site content by running a local server

1

bundle exec jekyll s

After a few seconds, the local service will be published at http://127.0.0.1:4000

To build your site in production mode

1

JEKYLL_ENV=production bundle exec jekyll b

This will output the production site to _site. You can upload this to a server to deploy your site manually.

Deploy site

This site is already configured to automatically deploy to Github pages using Github actions.

  1. Go to your repository on GitHub. Select the Settings tab, then click Pages in the left navigation bar. In the Source section (under Build and deployment), select GitHub Actions from the dropdown menu.
  2. Now all you have to do is push the changes to Github.
    1
2
3

    git add .
git commit -m "made some changes"
git push

In the Actions tab of your repository, you should see the workflow Build and Deploy running. Once the build is complete and successful, the site will be deployed automatically.

You can now visit the URL provided by GitHub to access your site. (Which is usually USERNAME.github.io)

  • If you’re on the GitHub Free plan, keep your site repository public.

Usage

Configure your Profile

Update the variables in _config.yml as needed. Make sure to set the following variables correctly:

  • title
  • url
  • avatar
  • timezone
  • lang
  • usernames

Social contact options are displayed at the bottom of the sidebar. You can enable or disable specific contacts in the _data/contact.yml file.

Creating a post

You can write posts using the markdown format. All posts are stored in the _posts folder. Jekyll uses a naming convention for pages and posts.

To create a post, add a file to your _posts directory with the following format: YYYY-MM-DD-title.md.

All blog post files must begin with Front Matter which is typically used to set a layout or other meta data.

Recommended Front Matter for Chirpy

1
2
3
4
5
6
7

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG names should always be lowercase
description: Short summary of the post.
---

Local Linking of Files

Image from asset:

1
2
3
4
5

... which is shown in the screenshot below:
![A screenshot](/assets/screenshot.webp)

You can also specify dimensions
![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

Linking to a file

1

... you can [download the PDF](/assets/diagram.pdf) here.

For additional information, checkout:

If you need some help with markdown, check out the markdown cheat sheet.

Troubleshooting

If auto regeneration is not working, try

1

jekyll serve --force_polling

If bundle command is not working

  1. Try updating your gems using gem update.

If bundle exec jekyll s is not working

  1. Check output and see if any particular gem is giving problems.
  2. try bundle exec jekyll build
  3. or try bundle exec jekyll serve --no-watch
    • As a workaround, you could use two terminal windows: one running bundle exec jekyll build --watch to rebuild your site when files change, and another running a simple HTTP server to serve your _site directory: cd _site python -m http.server 4000` This last option would allow you to work on your site with live reloading, even if the Jekyll server itself isn’t working.

If a specific gem is giving trouble,

  1. Reinstall that gem
    1
2

     gem uninstall ffi
 gem install ffi
  2. If that doesn’t work, try reinstalling all your gems:
    1
2

     bundle clean --force
 bundle install
  3. Make sure you are using the correct version and platform of the gem.
    1. Check ruby -v and gem list [gem-name] or gem info [gem-name.
    2. If it’s not same
      1
2

       gem uninstall ffi
 gem install ffi --platform=ruby

      or install from local file: gem install --local [pathtofile/gemname]

    3. rebuild your bundle: bundle install

Checkout https://jekyllrb.com/docs/troubleshooting/

Other jekyll templates

website, html, static site, SSG, markdown, jekyll, chirpy
This post is licensed under CC BY 4.0 by the author.