0xnhl

Back

The Ultimate Jekyll Blogging Guide

Created: 1/12/2026 Updated: 1/12/2026
#website#html#static site#ssg#markdown#jekyll#chirpy

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.

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

To avoid installing RubyGems packages as the root user:

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

Install Jekyll and Bundler

gem install jekyll bundler
bash

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 
    cd repo-name
bundle
    bash

Checkout Chirpy docs here ↗.

Build site#

To preview the site content by running a local server

bundle exec jekyll s
bash

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

To build your site in production mode

JEKYLL_ENV=production bundle exec jekyll b
bash

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.
git add .
git commit -m "made some changes"
git push
bash

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

---
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.
---
markdown

Local Linking of Files#

... which is shown in the screenshot below:
A screenshot

You can also specify dimensions
Desktop View{: w="700" h="400" }
markdown

Linking to a file

... you can download the PDF here.
markdown

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

jekyll serve --force_polling
bash

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 
    gem uninstall ffi
gem install ffi
    shell
  2. If that doesn’t work, try reinstalling all your gems: 
    bundle clean --force
bundle install
    shell
  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 
      gem uninstall ffi
gem install ffi --platform=ruby
      shell
    or install from local file: gem install --local [pathtofile/gemname]
    3. rebuild your bundle: bundle install

Checkout https://jekyllrb.com/docs/troubleshooting/ ↗
{: .prompt-tip }

Other jekyll templates