Jekyll: The simplest way to create static websites with GitHub Pages

When I began my career as a web developer, I always thought I needed to set up a complex server or learn advanced technologies to create a decent website. To my surprise, one day I discovered Jekyll and it completely changed my perspective on static web development. In this article, I want to share why Jekyll has become one of my favorite tools and how you can leverage it to create impressive websites with minimal effort.

What is Jekyll?

Jekyll is a static site generator, developed in Ruby, that transforms plain text files into a fully functional website or blog. Unlike traditional CMS like WordPress, which require a database and server-side code, Jekyll generates static HTML files that can be hosted on any web server.

The most interesting thing is that GitHub Pages works with Jekyll under the hood, which means you can deploy your website directly from your GitHub repository without additional configurations.

Ideal use cases for Jekyll

Jekyll especially stands out in certain scenarios worth considering:

Personal blogs and portfolios

Jekyll was originally designed as a blog engine, and it remains one of its most common applications. The post-oriented structure, support for categories and tags, and the ease of creating static pages make it ideal for:

• Development blogs
• Professional portfolios
• Personal sites

Open source project sites

The integration with GitHub Pages makes Jekyll perfect for open source projects:

• Technical documentation for projects
• Presentation pages for libraries or frameworks
• Wikis for collaborative projects

Sites with limited budget

For small organizations, startups, or individuals with limited budget, Jekyll offers:

• Free hosting on GitHub Pages
• No server maintenance costs
• No need for constant security updates

Projects that prioritize security

By generating completely static sites, Jekyll eliminates many common attack vectors:

• No databases that can be compromised
• No server-side code that might contain vulnerabilities
• Smaller attack surface overall

How to get started with Jekyll and GitHub Pages

Let’s see step by step how to create your first site with Jekyll and deploy it on GitHub Pages:

Step 1: Installing Jekyll

To install Jekyll, you need Ruby and RubyGems installed on your system. Then, you can install Jekyll with:

gem install jekyll bundler

Step 2: Create a new Jekyll site

Create a new Jekyll site with:

jekyll new my-awesome-site
cd my-awesome-site

Step 3: Local preview

You can preview your site locally with:

bundle exec jekyll serve

Now visit http://localhost:4000 in your browser to see your site.

Step 4: Basic configuration

The _config.yml file is the heart of your Jekyll site’s configuration. Here you can define the title, description, theme, and other options:

title: My Awesome Site
description: >-
  This is my new website created with Jekyll and GitHub Pages.
baseurl: '' # If your site is on a subdomain of GitHub Pages
url: 'https://yourusername.github.io' # The base URL of your site
theme: minima # The theme you want to use

Step 5: Create content

Jekyll uses Markdown for content. To create a new post, add a file in the _posts folder following the naming convention YYYY-MM-DD-title-of-the-post.md:

---
layout: post
title: 'My first post with Jekyll'
date: 2023-03-23
categories: jekyll tutorial
---

This is my first post using Jekyll. It's incredibly easy to create content!

Step 6: Deploy on GitHub Pages

1. Create a new repository on GitHub
2. Initialize Git in your local directory and connect with the remote repository:

git init
git add .
git commit -m "First commit"
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git push -u origin main

3. Go to the repository settings, navigate to the “Pages” section and select the main branch as the source.

And that’s it! Your site will be available at https://yourusername.github.io in a few minutes.

Templates and themes: Effortless customization

One of the most attractive features of Jekyll is the abundance of available themes. Some places where you can find free and premium themes:

• Jekyll Themes
• GitHub Pages Themes
• JekyllThemes.org
• RubyGems

Installing a theme is as simple as adding a line to your _config.yml or installing the corresponding gem.

Beyond the basics: Empowering Jekyll

Collections

Collections allow you to group related content that doesn’t necessarily follow a chronological structure like posts:

# In _config.yml
collections:
  projects:
    output: true

Then you create a _projects folder and add Markdown files for each project.

Data Files

Jekyll allows you to load data from YAML, JSON, or CSV files in the _data folder:

- name: Twitter
  url: https://twitter.com/yourusername
  icon: twitter

- name: GitHub
  url: https://github.com/yourusername
  icon: github

Which you can use in your templates:

{% for network in site.data.social_networks %}
  <a href="{{ network.url }}">{{ network.name }}</a>
{% endfor %}

Jekyll vs. Other Static Site Generators

The ecosystem of static site generators (SSGs) and documentation tools has grown considerably in recent years. Let’s compare Jekyll with some of the most popular alternatives to understand why it might be the best option for many use cases.

Static Site Generators (SSGs)

Data extracted from my open source project Free For Geeks: Static Site Generator

What distinguishes Jekyll:

1. Native GitHub Pages integration: Unlike its competitors, Jekyll is the only option directly integrated with GitHub Pages without additional configuration.

2. Simplicity over complexity: While Hugo is faster and Gatsby more powerful in certain aspects, Jekyll maintains a perfect balance between functionality and ease of use.

3. Maturity and stability: With over a decade of development, Jekyll has an established community and a stable codebase, unlike newer options that can change rapidly.

4. Focus on content: Jekyll is designed to let you focus on writing content in Markdown, not on learning technical complexities.

Specialized Documentation Tools

Data about documentation tools extracted from my open source project Free For Geeks: Documentation

Why choose Jekyll over documentation tools?

1. Versatility: While tools like Docsify or MkDocs are optimized exclusively for documentation, Jekyll is versatile and can serve for blogs, portfolios, corporate sites, documentation, and more.

2. Total control: Jekyll gives you complete control over the structure and design of your site, unlike more opinionated solutions like GitBook.

3. No JavaScript dependency: Unlike Docsify which requires JavaScript to function, Jekyll sites are pure HTML and work even with JavaScript disabled.

4. Single ecosystem: With Jekyll you can use the same system for your blog, documentation, and website, without needing to learn multiple tools.

Why Jekyll might be your best option

Jekyll remains relevant in 2025 for several reasons:

1. Simplicity: In a world of increasingly complex frameworks, Jekyll keeps things simple.
2. Security: Without databases or dynamic code, Jekyll sites are inherently more secure.
3. Low cost: With GitHub Pages, you can host your site for free.
4. Integrated version control: Your entire site is under version control in Git.
5. SEO-friendly: Static sites tend to load faster, which favors SEO.
6. Focus on content: Jekyll allows you to focus on writing, not on fighting with technology.

My projects with Jekyll

I have used Jekyll in several personal projects, attracted by its simplicity and flexibility. Its focus on content creation has allowed me to develop efficient websites tailored to my needs, avoiding complex configurations. I especially value the ability to use themes and plugins to customize the appearance and functionality of my sites, as well as the integration with GitHub Pages and the large community of developers that supports it.

Conclusion

Jekyll and GitHub Pages form an unbeatable combination for developers looking for a simple, fast, and economical solution to create static websites. Although there are more modern alternatives like Hugo, Gatsby, or specialized tools like Docusaurus, Jekyll’s simplicity and native integration with GitHub Pages make it a hard option to beat for many projects.

From personal blogs to project documentation or professional portfolios, Jekyll offers surprising flexibility without the complexity of other platforms. You don’t need to be a programming expert to create a professional website with Jekyll.

If you’ve never tried Jekyll, I encourage you to give it a chance. You might discover, as I did, that sometimes the simplest technologies are the ones that offer the best development experience.

Have you used Jekyll for any project? Have you tried other alternatives like Hugo or Docsify? Do you have any questions about how to implement specific functionalities? Leave me a comment and let’s continue the conversation!

Additional resources:

• I also wrote about Jekyll at docs.jpdiaz.dev
• Official Jekyll documentation
• GitHub Pages guide
• Awesome Jekyll - A collection of awesome resources and plugins for Jekyll
• Free For Geeks - My open source project about tools and resources for developers